{
  "openapi": "3.0.0",
  "paths": {
    "/leads": {
      "post": {
        "description": "Submit a lead for a dealership your partner account is associated with.\n\nThe partner is identified by the credential, so there is no partner id in the path. Everything else matches v1: the same body, the same deny-by-default dealership rules, and the same `409` on a repeated `callerReferenceId`.",
        "operationId": "submitLeadV2",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitLeadV2Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lead accepted",
            "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 credential"
          },
          "403": {
            "description": "Credential lacks `leads:write`, or the partner is not authorized for this organization"
          },
          "409": {
            "description": "Duplicate callerReferenceId",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DuplicateLeadResponseV1Dto"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded for this partner. The response body carries `retryAfterMs` — the wait before the current window frees up. No rate-limit headers are sent on this status; read them from a successful response instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitExceededResponseV2Dto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Submit a lead",
        "tags": [
          "leads"
        ]
      },
      "get": {
        "description": "Look up a previously submitted lead using your own reference id — the same value you passed on submission. Use it to check whether a lead was already submitted before retrying, or to poll for status.\n\nRequires `leads:write`: on v1 the same credential covers both, and a narrower read scope would leave migrating partners unable to call a route they can call today.",
        "operationId": "lookupLeadV2",
        "parameters": [
          {
            "name": "callerReferenceId",
            "required": true,
            "in": "query",
            "description": "Your reference id for the lead",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lead found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupLeadResponseV2Dto"
                }
              }
            }
          },
          "400": {
            "description": "Missing or empty `callerReferenceId`"
          },
          "401": {
            "description": "Missing, invalid or expired credential"
          },
          "404": {
            "description": "No lead found for this `callerReferenceId`"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Look up a lead by callerReferenceId",
        "tags": [
          "leads"
        ]
      }
    },
    "/me": {
      "get": {
        "description": "Returns the partner this credential authenticates as and the scopes it holds.\n\nCall it at startup. A scope you were not granted is a `403` at the point of use; checking here turns that into a startup failure with a name attached.\n\nUnlike v1, the partner is derived from your token, not from the URL — there is no `{partnerId}` path segment in v2.",
        "operationId": "me",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerIdentityV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Describe the calling credential",
        "tags": [
          "me"
        ]
      }
    },
    "/deals": {
      "get": {
        "operationId": "listDealsV2",
        "parameters": [
          {
            "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"
            }
          },
          {
            "name": "callerReferenceId",
            "required": false,
            "in": "query",
            "description": "Only the offers or deals started from the invitation you sent with this `callerReferenceId`. A reference you never sent returns an empty page.",
            "schema": {
              "example": "INV-20261103-0042",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "_meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PartnerDealResponseV2"
                      }
                    },
                    "_meta": {
                      "$ref": "#/components/schemas/PartnerPageMetaV2"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List deals your organization is party to",
        "tags": [
          "deals"
        ]
      }
    },
    "/deals/{dealId}": {
      "get": {
        "operationId": "getDealV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerDealResponseV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get one deal",
        "tags": [
          "deals"
        ]
      }
    },
    "/offers": {
      "get": {
        "operationId": "listOffersV2",
        "parameters": [
          {
            "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"
            }
          },
          {
            "name": "callerReferenceId",
            "required": false,
            "in": "query",
            "description": "Only the offers or deals started from the invitation you sent with this `callerReferenceId`. A reference you never sent returns an empty page.",
            "schema": {
              "example": "INV-20261103-0042",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "_meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PartnerOfferResponseV2"
                      }
                    },
                    "_meta": {
                      "$ref": "#/components/schemas/PartnerPageMetaV2"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List offers your organization is party to",
        "tags": [
          "offers"
        ]
      },
      "post": {
        "description": "Sends an offer between a buyer and seller, and returns a deep link for each party. No deal exists until the counterparty accepts.\n\nIf this VIN is not already listed under your account, `year`, `make` and `model` are required alongside `vin`. A listing owned by another dealer, partner or PrivateAuto user does not count.\n\n`offerId` is always returned. `dealId` is returned when a deal exists — it is `null` before the invitation is accepted. Use `guid` as your stable cross-system handle: it is unchanged from v1 and appears on every related webhook payload.\n\nA repeated call for the same VIN and parties returns the open invitation (`offerId`, `guid`, links, and `dealId` once someone has joined) instead of creating a new one.\n\n**`callerReferenceId`** (optional) makes the call idempotent on your own reference. Sent again with the same VIN, buyer email and seller email, it returns the original invitation (`offerId`, `guid`, `dealId` once someone has joined, and links) and changes nothing: no terms are rewritten and no email is sent. Replayed links never carry a sign-in token, so the counterparty signs in normally. Sent with a different VIN or emails, it returns 409 `duplicate_reference` with the existing `offerId` and a `redirectUrl` (the generic error page in the user's app, safe to send them to).\n\n**Sides, dealer and price, stated outright** (optional; the inferred forms below keep working unchanged). `partnerSide` (`buyer` or `seller`) says which side you are on, and `counterparty` names the other party (`email`, optional `name` and `sendLink`), so nothing is inferred from which email is filled. `dealerOrganizationId` or `dealerExternalId` names the dealership the deal is for instead of matching emails to dealership users; it must be your organization or a linked dealership, else 403 `dealer_not_authorized`. `price` is the offered price in US dollars and replaces `amount`. A new field sent with its old counterpart must agree, else 400 (`counterparty_conflict`, `price_conflict`).\n\nReplaces `POST /v2/deal-invites`, which remains as a deprecated alias.\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": "sendOfferV2",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDealInviteV2Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DealInviteResponseV2"
                }
              }
            }
          },
          "403": {
            "description": "`dealer_not_authorized`: the named dealership is not yours or linked to your partner account"
          },
          "409": {
            "description": "`duplicate_reference`: the reference is already used for another invitation. Carries the existing `offerId`, and `redirectUrl`, the error page to send the user to",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DuplicateReferenceResponseV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Send an offer",
        "tags": [
          "offers"
        ]
      }
    },
    "/offers/{offerId}": {
      "get": {
        "operationId": "getOfferV2",
        "parameters": [
          {
            "name": "offerId",
            "required": true,
            "in": "path",
            "description": "Offer id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerOfferResponseV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get one offer",
        "tags": [
          "offers"
        ]
      }
    },
    "/vehicles": {
      "get": {
        "description": "Returns vehicles. Each carries its current sale listing under `listing` — present for every vehicle today, since a vehicle reaches the API by being listed, but declared nullable for vehicles that will exist without one.\n\nUse `ownership` to separate inventory you listed for sale from vehicles you bought through PrivateAuto, and `expand=deals` to include each vehicle’s completed sales and latest DealNow id. Both are opt-in; omitting them returns every vehicle with no extra joins.",
        "operationId": "listVehiclesV2",
        "parameters": [
          {
            "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"
            }
          },
          {
            "name": "ownership",
            "required": false,
            "in": "query",
            "description": "Limit to vehicles your organization listed for sale (`listed`) or bought through PrivateAuto (`purchased`).\n\n**These two do not add up to the whole collection.** Omit the parameter to return every vehicle, including ones removed from sale — which `listed` excludes and `purchased` does not cover. If you are reconciling inventory and need the complete set, omit the parameter rather than enumerating both values.",
            "schema": {
              "type": "string",
              "enum": [
                "listed",
                "purchased"
              ]
            }
          },
          {
            "name": "expand",
            "required": false,
            "in": "query",
            "description": "Optional joins. `deals` adds each vehicle’s completed sales and its latest DealNow id. Repeat the parameter or pass a comma-separated list.",
            "schema": {
              "example": [
                "deals"
              ],
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "deals"
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "_meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PartnerVehicleResponseV2"
                      }
                    },
                    "_meta": {
                      "$ref": "#/components/schemas/PartnerPageMetaV2"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List vehicles your organization has listed",
        "tags": [
          "vehicles"
        ]
      },
      "post": {
        "description": "Creates a vehicle and its sale listing.\n\nThe listing is created as `pending`, exactly as one created through the app is — this endpoint does not publish it.\n\n`listingNo`, `slug` and the listing location are derived server-side and cannot be supplied. Sending any field not documented below is a `400` naming that field.\n\n**Free-text search lags creation.** The marketplace matches free text against search terms derived asynchronously after the write, so a new listing is readable here and reachable by URL before it is returned by a text search. Distance-filtered search additionally requires `zip`.",
        "operationId": "listVehicleV2",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListVehicleV2Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Vehicle listed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehicleResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "Validation error, unknown field, or an unresolvable `zip`"
          },
          "401": {
            "description": "Missing, invalid or expired credential"
          },
          "403": {
            "description": "Credential lacks `vehicles:write`"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List a vehicle for sale",
        "tags": [
          "vehicles"
        ]
      }
    },
    "/vehicles/{vehicleId}": {
      "get": {
        "operationId": "getVehicleV2",
        "parameters": [
          {
            "name": "vehicleId",
            "required": true,
            "in": "path",
            "description": "Vehicle id — the `id` of a vehicle from the list response. A vehicle and its listing are one record today, so this is also the id v1 publishes for the listing. VIN is not accepted: it is absent on a significant share of stock, so it cannot address every vehicle.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehicleResponseV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get one vehicle",
        "tags": [
          "vehicles"
        ]
      }
    },
    "/vehicles/{vehicleId}/listing": {
      "patch": {
        "description": "Updates the sale listing of a vehicle your organization owns. Only the price is mutable; status changes go through the dedicated verbs so a transition can never be made by accident.",
        "operationId": "updateVehicleListingV2",
        "parameters": [
          {
            "name": "vehicleId",
            "required": true,
            "in": "path",
            "description": "Vehicle id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateVehicleListingV2Dto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehicleResponseV2"
                }
              }
            }
          },
          "404": {
            "description": "No such vehicle in your organization"
          },
          "409": {
            "description": "The vehicle is in a terminal state (sold or purchased) and cannot be repriced"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Change the asking price",
        "tags": [
          "vehicles"
        ]
      }
    },
    "/vehicles/{vehicleId}/listing/deactivate": {
      "post": {
        "description": "Withdraws the listing. Idempotent — deactivating an already-deactivated vehicle succeeds and returns the same state, so a retry after a timeout is safe. A sold vehicle cannot be withdrawn.",
        "operationId": "deactivateVehicleListingV2",
        "parameters": [
          {
            "name": "vehicleId",
            "required": true,
            "in": "path",
            "description": "Vehicle id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehicleResponseV2"
                }
              }
            }
          },
          "404": {
            "description": "No such vehicle in your organization"
          },
          "409": {
            "description": "The vehicle is in a terminal state (sold or purchased) and cannot be withdrawn"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Take a vehicle off the market",
        "tags": [
          "vehicles"
        ]
      }
    },
    "/vehicles/{vehicleId}/listing/publish": {
      "post": {
        "description": "Takes a `pending` listing live.\n\nRequires `vehicles:publish`, which is **not** granted by default — ask PrivateAuto to enable it for your account.\n\nPublishing also requires your dealership to hold an active PrivateAuto subscription; without one this returns `402` rather than publishing, since going live is what the subscription pays for.\n\nIdempotent: publishing an already-live listing succeeds and does not restart its live window. A withdrawn listing must be reactivated first.",
        "operationId": "publishVehicleListingV2",
        "parameters": [
          {
            "name": "vehicleId",
            "required": true,
            "in": "path",
            "description": "Vehicle id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehicleResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "Your partner account has no organization scope — the same condition every other v2 route reports this way. Contact PrivateAuto support."
          },
          "402": {
            "description": "The dealership has no active subscription"
          },
          "403": {
            "description": "Credential lacks `vehicles:publish`"
          },
          "404": {
            "description": "No such vehicle in your organization"
          },
          "409": {
            "description": "The vehicle is not in a publishable state — reactivate a withdrawn listing first"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Publish a vehicle to the marketplace",
        "tags": [
          "vehicles"
        ]
      }
    },
    "/vehicles/{vehicleId}/listing/reactivate": {
      "post": {
        "description": "The counterpart to deactivate. Returns the listing to `pending`; it does not publish, for the same reason creating does not.\n\nWithout this, withdrawing would be irreversible over the API and the only way back would be creating the vehicle again — a duplicate with a new listing number, slug and public URL. Idempotent, so a retry is safe.",
        "operationId": "reactivateVehicleListingV2",
        "parameters": [
          {
            "name": "vehicleId",
            "required": true,
            "in": "path",
            "description": "Vehicle id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehicleResponseV2"
                }
              }
            }
          },
          "404": {
            "description": "No such vehicle in your organization"
          },
          "409": {
            "description": "The vehicle is sold and cannot be relisted"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Put a withdrawn vehicle back on the market",
        "tags": [
          "vehicles"
        ]
      }
    },
    "/vehicles/{vehicleId}/photos": {
      "get": {
        "operationId": "listVehiclePhotosV2",
        "parameters": [
          {
            "name": "vehicleId",
            "required": true,
            "in": "path",
            "description": "Vehicle id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehiclePhotosResponseV2"
                }
              }
            }
          },
          "404": {
            "description": "No such vehicle in your organization"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List the photos on a vehicle, in display order",
        "tags": [
          "vehicles"
        ]
      },
      "post": {
        "description": "Multipart `file` — JPEG, PNG or WebP, up to 15 MB. The photo is appended at the end; the first photo on a vehicle becomes its cover. Use the reorder route to move it.\n\nIdempotent on content: uploading the same bytes again returns the current list without adding a duplicate, so a retry after a timeout is safe. A vehicle can hold at most 100 photos.",
        "operationId": "addVehiclePhotoV2",
        "parameters": [
          {
            "name": "vehicleId",
            "required": true,
            "in": "path",
            "description": "Vehicle id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/AddVehiclePhotoV2Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehiclePhotosResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "No `file` in the request"
          },
          "404": {
            "description": "No such vehicle in your organization"
          },
          "409": {
            "description": "The vehicle is sold or purchased, or already has 100 photos"
          },
          "413": {
            "description": "The file is larger than 15 MB"
          },
          "415": {
            "description": "Not a JPEG, PNG or WebP, or the content does not match its type"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Add a photo to a vehicle",
        "tags": [
          "vehicles"
        ]
      }
    },
    "/vehicles/{vehicleId}/photos/{photoId}": {
      "delete": {
        "description": "Removes the photo from the vehicle and closes the gap; if it was the cover, the next photo becomes the cover. A live vehicle must keep at least one photo.",
        "operationId": "removeVehiclePhotoV2",
        "parameters": [
          {
            "name": "vehicleId",
            "required": true,
            "in": "path",
            "description": "Vehicle id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "photoId",
            "required": true,
            "in": "path",
            "description": "Photo id, from the photos list",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehiclePhotosResponseV2"
                }
              }
            }
          },
          "404": {
            "description": "No such vehicle in your organization, or no such photo on it"
          },
          "409": {
            "description": "The vehicle is sold or purchased, or this is the last photo on a live vehicle"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Remove a photo from a vehicle",
        "tags": [
          "vehicles"
        ]
      }
    },
    "/vehicles/{vehicleId}/photos/order": {
      "put": {
        "description": "Send every current photo id once, in the order to display them. The first becomes the cover photo. A list that leaves a photo out or names one that is not on the vehicle is rejected with `409 photo_set_mismatch` and the ids involved — nothing is partially applied. Idempotent.",
        "operationId": "reorderVehiclePhotosV2",
        "parameters": [
          {
            "name": "vehicleId",
            "required": true,
            "in": "path",
            "description": "Vehicle id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReorderVehiclePhotosV2Dto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerVehiclePhotosResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "Malformed body or duplicate ids"
          },
          "404": {
            "description": "No such vehicle in your organization"
          },
          "409": {
            "description": "The list does not match the vehicle’s current photos, the photos changed mid-request, or the vehicle is sold or purchased"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Set the display order of a vehicle’s photos",
        "tags": [
          "vehicles"
        ]
      }
    },
    "/webhooks/deliveries": {
      "get": {
        "description": "What we sent, what we skipped, and what failed. The first place to look when you believe an event is missing — it usually shows either a delivery you returned non-2xx to, or that the event never qualified.",
        "operationId": "listWebhookDeliveriesV2",
        "parameters": [
          {
            "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": "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"
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Filter by delivery status. `dlq` is an event we gave up on: delivery failed repeatedly and was abandoned, so it never reached you and will not be retried automatically. Treat a `dlq` row as a delivery you must reconcile from the API rather than wait for.",
            "schema": {
              "type": "string",
              "enum": [
                "delivered",
                "failed",
                "skipped",
                "dlq"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "_meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PartnerWebhookDeliveryResponseV2"
                      }
                    },
                    "_meta": {
                      "$ref": "#/components/schemas/PartnerPageMetaV2"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List webhook delivery attempts",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/deliveries/{logId}": {
      "get": {
        "operationId": "getWebhookDeliveryV2",
        "parameters": [
          {
            "name": "logId",
            "required": true,
            "in": "path",
            "description": "Delivery log id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWebhookDeliveryResponseV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get one webhook delivery attempt",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/deals/{dealId}/documents": {
      "get": {
        "description": "Signed URLs are short-lived — each carries `filename` and `expiresAt`. Re-fetch rather than store.",
        "operationId": "getDealDocumentsV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerDealDocumentsResponseV1"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "All documents on a deal, with fresh signed URLs",
        "tags": [
          "documents"
        ]
      },
      "post": {
        "description": "Multipart `file` + `documentType` + `callerReferenceId` (+ optional `description`). Idempotent on `callerReferenceId`. 404 if the deal is not in your scope, 409 `deal_not_uploadable` if it is cancelled/expired, 409 `duplicate_reference` if the reference is reused with a different file.",
        "operationId": "uploadDealDocumentV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal 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"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Upload a document onto a deal",
        "tags": [
          "documents"
        ]
      }
    },
    "/documents/{documentId}": {
      "get": {
        "operationId": "getDocumentV2",
        "parameters": [
          {
            "name": "documentId",
            "required": true,
            "in": "path",
            "description": "Document id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerDocumentDetailResponseV1"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "One uploaded document, with a fresh signed URL",
        "tags": [
          "documents"
        ]
      },
      "delete": {
        "description": "Hides a document you uploaded — never a hard delete. 404 if it is not your upload, 409 `document_acted_on` if it has been signed or acknowledged (replace it rather than voiding).",
        "operationId": "voidDealDocumentV2",
        "parameters": [
          {
            "name": "documentId",
            "required": true,
            "in": "path",
            "description": "Document id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Voided — returns `{ documentId, status: \"voided\" }`"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Soft-void a document you uploaded",
        "tags": [
          "documents"
        ]
      }
    },
    "/generated-documents/{documentId}": {
      "get": {
        "operationId": "getGeneratedDocumentV2",
        "parameters": [
          {
            "name": "documentId",
            "required": true,
            "in": "path",
            "description": "Document id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerGeneratedDocumentDetailResponseV1"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "One PrivateAuto-generated document, with a fresh signed URL",
        "tags": [
          "documents"
        ]
      }
    },
    "/offers/widget": {
      "post": {
        "description": "Browser-safe variant of `POST /v2/offers` for an embeddable make-offer widget.\n\n**Auth:** send your **publishable key** in the `X-PA-Widget-Key` header; no Authorization header. The key identifies your partner account. The request is accepted only when the request `Origin` (or `Referer`) host is in your configured widget origins, and your credential grant includes `deal-invites:write`.\n\nRate limited to 10 requests per minute per client IP, counted across this path and its deprecated alias `POST /v2/deal-invites/widget` together.\n\nBody and response are identical to `POST /v2/offers`, except: `buyerSendLink` / `sellerSendLink` are ignored and no email is sent (show or deliver the returned links yourself); a posted email always names the counterparty (`buyerEmail` → you are the seller; `sellerEmail` or no email → you are the buyer) and is never matched to an existing account (the counterparty is bound when they follow their link); posting both emails is rejected with 400; `callerReferenceId` is not accepted (400), so a widget call is never replayed and its response `callerReferenceId` is always null; and `partnerSide`, `counterparty`, `dealerOrganizationId`, `dealerExternalId` and `price` are not accepted (400): a publishable key cannot vouch for a side or a dealer, so send the price as `amount`.\n\nReplaces `POST /v2/deal-invites/widget`, which remains as a deprecated alias.",
        "operationId": "sendOfferFromWidgetV2",
        "parameters": [
          {
            "name": "x-pa-widget-key",
            "in": "header",
            "description": "Your widget publishable key (non-secret).",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiateDealNowV1Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DealInviteResponseV2"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unknown widget key, or Origin/Referer not allowed"
          },
          "403": {
            "description": "Your credential grant does not include deal-invites:write"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        },
        "summary": "Send an offer from an embedded widget (publishable key)",
        "tags": [
          "offers"
        ]
      }
    },
    "/deal-invites": {
      "post": {
        "deprecated": true,
        "description": "**Deprecated.** Use `POST /v2/offers`. This path is an alias kept for existing integrations: the request, response, authentication, scopes and rate limits are identical. Every response that passes the authentication, scope and rate-limit checks carries `Deprecation: true` and `Link: </v2/offers>; rel=\"successor-version\"`.",
        "operationId": "createDealInviteV2",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDealInviteV2Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "headers": {
              "Deprecation": {
                "description": "Always `true`: this path is deprecated.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "`</v2/offers>; rel=\"successor-version\"`: the path to call instead.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DealInviteResponseV2"
                }
              }
            }
          },
          "403": {
            "description": "`dealer_not_authorized`: the named dealership is not yours or linked to your partner account"
          },
          "409": {
            "description": "`duplicate_reference`: the reference is already used for another invitation. Carries the existing `offerId`, and `redirectUrl`, the error page to send the user to",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DuplicateReferenceResponseV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Start a transaction and get per-party deep links",
        "tags": [
          "deal-invites"
        ]
      }
    },
    "/deal-invites/widget": {
      "post": {
        "deprecated": true,
        "description": "**Deprecated.** Use `POST /v2/offers/widget`. This path is an alias kept for existing integrations: the request, response, authentication, scopes and rate limits are identical, and the rate limit counts requests to both paths together. Every response that passes the authentication, scope and rate-limit checks carries `Deprecation: true` and `Link: </v2/offers/widget>; rel=\"successor-version\"`.",
        "operationId": "createDealInviteFromWidgetV2",
        "parameters": [
          {
            "name": "x-pa-widget-key",
            "in": "header",
            "description": "Your widget publishable key (non-secret).",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiateDealNowV1Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "headers": {
              "Deprecation": {
                "description": "Always `true`: this path is deprecated.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "`</v2/offers/widget>; rel=\"successor-version\"`: the path to call instead.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DealInviteResponseV2"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unknown widget key, or Origin/Referer not allowed"
          },
          "403": {
            "description": "Your credential grant does not include deal-invites:write"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        },
        "summary": "Start a transaction from an embedded widget (publishable key)",
        "tags": [
          "deal-invites"
        ]
      }
    },
    "/deals/{dealId}/offers": {
      "post": {
        "description": "Supersedes the current offer with a new price from your side. 409 `invalid_transition` if the deal is not in a state that accepts a counter; 503 `deal_first_not_enabled` where the lifecycle is not yet live.",
        "operationId": "counterOfferV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CounterOfferV2Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Counter the live offer on a deal",
        "tags": [
          "offers"
        ]
      }
    },
    "/deals/{dealId}/offers/accept": {
      "post": {
        "description": "Accepting the working price is what opens the deal (`negotiating` → `active`). Terms confirmation is a later step on the resulting deal, not a precondition. 409 `competing_active_deal` if another buyer’s deal already went active on this listing — a business outcome, not a fault, and not worth retrying.",
        "operationId": "acceptOfferV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Accept the live offer, opening the deal",
        "tags": [
          "offers"
        ]
      }
    },
    "/deals/{dealId}/offers/decline": {
      "post": {
        "operationId": "declineOfferV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Decline the live offer",
        "tags": [
          "offers"
        ]
      }
    },
    "/deals/{dealId}/offers/withdraw": {
      "post": {
        "operationId": "withdrawOfferV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Withdraw your own live offer",
        "tags": [
          "offers"
        ]
      }
    },
    "/deals/{dealId}/title/confirm": {
      "post": {
        "operationId": "confirmDealTitleV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConfirmTitleV2ResponseDto"
                }
              }
            }
          },
          "404": {
            "description": "No such deal, or your organization is not a party to it."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Confirm the title as your side",
        "tags": [
          "deals"
        ]
      }
    },
    "/deals/{dealId}/services": {
      "post": {
        "operationId": "updateDealServicesV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateServicePreferencesV2Dto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateServicesV2ResponseDto"
                }
              }
            }
          },
          "404": {
            "description": "No such deal, or your organization is not a party to it."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Set service preferences on the deal",
        "tags": [
          "deals"
        ]
      }
    },
    "/deals/{dealId}/cancel": {
      "post": {
        "description": "Refused with 409 `deal_not_cancellable` once any payment has a transfer date — a deal with money in flight cannot be cancelled through the API.",
        "operationId": "cancelDealV2",
        "parameters": [
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelDealV2ResponseDto"
                }
              }
            }
          },
          "404": {
            "description": "No such deal, or your organization is not a party to it."
          },
          "409": {
            "description": "`deal_not_cancellable` — money has moved, or there is nothing left to cancel."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Cancel the deal",
        "tags": [
          "deals"
        ]
      }
    },
    "/webhooks/endpoints": {
      "get": {
        "operationId": "listWebhookEndpointsV2",
        "parameters": [],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List your webhook endpoints",
        "tags": [
          "webhooks"
        ]
      },
      "post": {
        "description": "Returns the signing secret ONCE — no read path exposes it afterwards. The endpoint starts `unverified` and delivers nothing until it echoes the verification token. Destinations must be HTTPS and resolve to a public address.",
        "operationId": "createWebhookEndpointV2",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWebhookEndpointV2Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Register a webhook endpoint",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/endpoints/{endpointId}": {
      "get": {
        "operationId": "getWebhookEndpointV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get one webhook endpoint",
        "tags": [
          "webhooks"
        ]
      },
      "patch": {
        "description": "Changing the url returns the endpoint to `unverified` — a different destination needs its own proof.",
        "operationId": "updateWebhookEndpointV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWebhookEndpointV2Dto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update a webhook endpoint",
        "tags": [
          "webhooks"
        ]
      },
      "delete": {
        "description": "Stops delivery. Delivery history is retained and stays readable via /webhooks/deliveries.",
        "operationId": "deleteWebhookEndpointV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Remove a webhook endpoint",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/endpoints/{endpointId}/verify": {
      "post": {
        "description": "We call your endpoint; it must return 2xx AND echo the verification token in the body. Proving control of the destination requires a response from the destination — submitting the token here would only show you still have it. Returns `verified: false` with a reason rather than an error, so you can debug your listener.",
        "operationId": "verifyWebhookEndpointV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyWebhookEndpointV2ResponseDto"
                }
              }
            }
          },
          "429": {
            "description": "More than 10 verify/test requests in a minute"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Complete the ownership challenge",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/endpoints/{endpointId}/rotate-secret": {
      "post": {
        "description": "Returns the new secret ONCE. Deliveries switch to the new secret from the moment of the call, and within 5 minutes at the latest; accept both the old and the new until `previousSecretExpiresAt` (15 minutes), after which only the new one is used.",
        "operationId": "rotateWebhookSecretV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RotateWebhookSecretV2ResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Issue a new signing secret",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/endpoints/{endpointId}/test": {
      "post": {
        "description": "Signed exactly like a real delivery, so you can exercise signature verification before real traffic depends on it. Allowed on an unverified endpoint — this is the tool for working out why verification is failing. A non-2xx from your listener is reported as data, not an error.",
        "operationId": "testWebhookEndpointV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestWebhookEndpointV2ResponseDto"
                }
              }
            }
          },
          "429": {
            "description": "More than 10 verify/test requests in a minute"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Deliver a synthetic event",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/catalog": {
      "get": {
        "description": "Scoped to your credential rather than a static list, so anything shown here can actually be subscribed to. `notEntitled` names the namespaces you lack and the scope each would need.",
        "operationId": "getWebhookCatalogV2",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookCatalogV2Dto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Events THIS credential may subscribe to",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/endpoints/{endpointId}/subscriptions": {
      "put": {
        "description": "An unentitled event is refused with 403 naming it — never dropped silently from the set. An empty list means the endpoint receives nothing; it is inert, not a wildcard.",
        "operationId": "replaceWebhookSubscriptionsV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionsV2Dto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointV2Dto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Replace the whole subscription set",
        "tags": [
          "webhooks"
        ]
      },
      "post": {
        "operationId": "addWebhookSubscriptionsV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionsV2Dto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointV2Dto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Add to the subscription set",
        "tags": [
          "webhooks"
        ]
      },
      "delete": {
        "description": "The endpoint stays registered and verified, and receives nothing until you subscribe again.",
        "operationId": "clearWebhookSubscriptionsV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointV2Dto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Clear every subscription",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/endpoints/{endpointId}/subscriptions/{event}": {
      "delete": {
        "description": "Removing something you are not subscribed to is not an error — the end state is what you asked for.",
        "operationId": "removeWebhookSubscriptionV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event",
            "required": true,
            "in": "path",
            "description": "Event name or wildcard pattern",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointV2Dto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Remove one subscription",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/endpoints/{endpointId}/enable": {
      "post": {
        "description": "Use this after fixing a listener we disabled for sustained delivery failure, or to resume one you paused. Re-verification is not required — the url has not changed. The failure counter is reset, so the endpoint does not restart one failure away from being disabled again. Delivery does NOT replay events missed while it was disabled.",
        "operationId": "enableWebhookEndpointV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointV2Dto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Return a disabled endpoint to service",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/webhooks/endpoints/{endpointId}/disable": {
      "post": {
        "description": "Keeps the endpoint and its signing secret. Unlike DELETE, resuming needs no redeploy — and the state is distinct from the one we set after sustained failure, so you can tell your pause from ours.",
        "operationId": "disableWebhookEndpointV2",
        "parameters": [
          {
            "name": "endpointId",
            "required": true,
            "in": "path",
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointV2Dto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Pause delivery without deleting the endpoint",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/dealers": {
      "get": {
        "description": "Every dealership carrying one of your identifiers, with the PrivateAuto id to use elsewhere in this API. A dealership may appear with several of your ids where it has multiple rooftops.",
        "operationId": "listDealersV2",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DealerV2"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List the dealerships you have linked",
        "tags": [
          "dealers"
        ]
      }
    },
    "/dealers/{externalId}": {
      "get": {
        "description": "Look a dealership up by **your** identifier rather than ours, so you never have to keep a mapping table. An id you have not linked returns 404.",
        "operationId": "getDealerByExternalIdV2",
        "parameters": [
          {
            "name": "externalId",
            "required": true,
            "in": "path",
            "description": "Your identifier for the dealership",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DealerV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Resolve one of your dealer ids to a PrivateAuto dealership",
        "tags": [
          "dealers"
        ]
      }
    },
    "/marketplace/vehicles": {
      "get": {
        "description": "Searches every vehicle publicly listed for sale, not just your own — the only v2 read that is not scoped to your organization.\n\nThe corpus is exactly what a visitor to the website can see: live, public listings with a seller. Results carry what is already public about each vehicle; the seller’s identity is not included, and location is city and state only.\n\nRequires `marketplace:search`, which is **not** granted by default — ask PrivateAuto to enable it for your account.\n\nSearches the `privateauto` marketplace unless you name another. The default marketplace is open to every account, named or omitted; naming a different one returns `403` unless your account is on it.\n\nFree text (`q`) matches search terms derived shortly after a vehicle is listed, so a very recently published vehicle may be browsable before it is matchable by text.",
        "operationId": "searchMarketplaceV2",
        "parameters": [
          {
            "name": "marketplace",
            "required": false,
            "in": "query",
            "description": "Which marketplace to search. **Omit it and you get `privateauto`**, the platform default.\n\nThe default marketplace is searchable by any account, whether you name it or omit it. Naming a DIFFERENT marketplace returns `403` unless your account is on it.\n\nMore marketplaces are planned, so read the `marketplaces` field on each result rather than assuming everything came from the one you searched.",
            "schema": {
              "default": "privateauto",
              "type": "string",
              "enum": [
                "privateauto",
                "dealnow"
              ]
            }
          },
          {
            "name": "q",
            "required": false,
            "in": "query",
            "description": "Free-text search. Matches the search terms derived for each vehicle after it is listed, so a very recently published vehicle may not be matchable by text yet even though it is browsable.",
            "schema": {
              "example": "bmw 330i sport",
              "type": "string"
            }
          },
          {
            "name": "make",
            "required": false,
            "in": "query",
            "description": "Manufacturer",
            "schema": {
              "example": "BMW",
              "type": "string"
            }
          },
          {
            "name": "model",
            "required": false,
            "in": "query",
            "description": "Model name",
            "schema": {
              "example": "330i",
              "type": "string"
            }
          },
          {
            "name": "yearMin",
            "required": false,
            "in": "query",
            "description": "Earliest model year",
            "schema": {
              "example": 2015,
              "type": "number"
            }
          },
          {
            "name": "yearMax",
            "required": false,
            "in": "query",
            "description": "Latest model year",
            "schema": {
              "example": 2020,
              "type": "number"
            }
          },
          {
            "name": "priceMin",
            "required": false,
            "in": "query",
            "description": "Minimum asking price in dollars",
            "schema": {
              "example": 5000,
              "type": "number"
            }
          },
          {
            "name": "priceMax",
            "required": false,
            "in": "query",
            "description": "Maximum asking price in dollars",
            "schema": {
              "example": 30000,
              "type": "number"
            }
          },
          {
            "name": "mileageMax",
            "required": false,
            "in": "query",
            "description": "Maximum odometer reading",
            "schema": {
              "example": 80000,
              "type": "number"
            }
          },
          {
            "name": "bodyStyle",
            "required": false,
            "in": "query",
            "description": "Body style",
            "schema": {
              "example": "sedan",
              "type": "string"
            }
          },
          {
            "name": "fuel",
            "required": false,
            "in": "query",
            "description": "Fuel type",
            "schema": {
              "example": "gasoline",
              "type": "string"
            }
          },
          {
            "name": "transmission",
            "required": false,
            "in": "query",
            "description": "Transmission type",
            "schema": {
              "example": "automatic",
              "type": "string"
            }
          },
          {
            "name": "driveType",
            "required": false,
            "in": "query",
            "description": "Drive type",
            "schema": {
              "example": "AWD",
              "type": "string"
            }
          },
          {
            "name": "vehicleType",
            "required": false,
            "in": "query",
            "description": "Vehicle category",
            "schema": {
              "type": "string",
              "enum": [
                "Auto",
                "ATV/OHV",
                "Motorcycle",
                "RV",
                "Boat"
              ]
            }
          },
          {
            "name": "sort",
            "required": false,
            "in": "query",
            "description": "Relevance ordering is not offered yet.\n\n**Paging is not stable across ties.** Results are ordered by a single key, and vehicles sharing the same price, mileage or listing time have no defined order relative to each other — so a vehicle can appear on two pages, or on none, when you page through a large result set. A tiebreak cannot currently be added because the search index does not support sorting on the vehicle id. If you need an exact, complete enumeration, narrow the query until it fits one page rather than paging through it.",
            "schema": {
              "default": "newest",
              "type": "string",
              "enum": [
                "newest",
                "price_asc",
                "price_desc",
                "mileage_asc"
              ]
            }
          },
          {
            "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"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "_meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MarketplaceVehicleV2"
                      }
                    },
                    "_meta": {
                      "$ref": "#/components/schemas/PartnerPageMetaV2"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or expired credential"
          },
          "403": {
            "description": "Credential lacks `marketplace:search`"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Search vehicles for sale on the marketplace",
        "tags": [
          "marketplace"
        ]
      }
    },
    "/reports": {
      "get": {
        "description": "Current shares only: none expired or revoked. A report link lists just its own report.\n\nAuthenticate with a v2 credential holding `reports:read`, or with a report link token (`prl_…`) an admin sent you. A link opens one report and needs no scope. A link with a passcode also needs it in the `X-Report-Passcode` header; without it, or with a wrong one, the response is `401` with code `passcode_required`. An unknown, expired or revoked link is a plain `401`.",
        "operationId": "listReportsV2",
        "parameters": [
          {
            "name": "x-report-passcode",
            "in": "header",
            "description": "A report link's passcode, when it has one.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportListV2"
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown, expired or revoked credential or link, or a passcode is needed."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List the reports shared with you",
        "tags": [
          "reports"
        ]
      }
    },
    "/reports/{shareId}": {
      "get": {
        "description": "The report's layout and widgets. A `live` report shows the dashboard as it is now, a `snapshot` the version published when it was shared; both have this shape. Widget data is read separately, by widget id.\n\nAuthenticate with a v2 credential holding `reports:read`, or with a report link token (`prl_…`) an admin sent you. A link opens one report and needs no scope. A link with a passcode also needs it in the `X-Report-Passcode` header; without it, or with a wrong one, the response is `401` with code `passcode_required`. An unknown, expired or revoked link is a plain `401`.",
        "operationId": "getReportV2",
        "parameters": [
          {
            "name": "x-report-passcode",
            "in": "header",
            "description": "A report link's passcode, when it has one.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "shareId",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportV2"
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown, expired or revoked credential or link, or a passcode is needed."
          },
          "404": {
            "description": "No current report with this id is shared with you."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Read one report",
        "tags": [
          "reports"
        ]
      }
    },
    "/wallets": {
      "get": {
        "description": "Your organization's own wallets, and its locations' if it has any. Never a linked dealer's. A wallet or transaction outside your organization returns 404. An organization can have several wallets, at different providers; each names its organization and provider. A location with no wallet of its own gets an empty list.",
        "operationId": "listWalletsV2",
        "parameters": [
          {
            "name": "organizationId",
            "required": false,
            "in": "query",
            "description": "Only wallets of this organization: your own, or one of your locations. Any other id returns an empty list.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PartnerWalletResponseV2"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List your wallets",
        "tags": [
          "wallets"
        ]
      }
    },
    "/wallets/{walletId}": {
      "get": {
        "description": "Your organization's own wallets, and its locations' if it has any. Never a linked dealer's. A wallet or transaction outside your organization returns 404.",
        "operationId": "getWalletV2",
        "parameters": [
          {
            "name": "walletId",
            "required": true,
            "in": "path",
            "description": "Wallet id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWalletResponseV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get one wallet",
        "tags": [
          "wallets"
        ]
      }
    },
    "/wallets/{walletId}/transactions": {
      "get": {
        "description": "Newest first. Your organization's own wallets, and its locations' if it has any. Never a linked dealer's. A wallet or transaction outside your organization returns 404.",
        "operationId": "listWalletTransactionsV2",
        "parameters": [
          {
            "name": "walletId",
            "required": true,
            "in": "path",
            "description": "Wallet id",
            "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",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "completed",
                "failed",
                "cancelled"
              ]
            }
          },
          {
            "name": "type",
            "required": false,
            "in": "query",
            "description": "Transaction type, e.g. `transfer`",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "direction",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "in",
                "out"
              ]
            }
          },
          {
            "name": "from",
            "required": false,
            "in": "query",
            "description": "Created at or after this time",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "name": "to",
            "required": false,
            "in": "query",
            "description": "Created before this time",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "name": "dealId",
            "required": false,
            "in": "query",
            "description": "Only transactions of this deal",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "_meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PartnerWalletTransactionResponseV2"
                      }
                    },
                    "_meta": {
                      "$ref": "#/components/schemas/PartnerPageMetaV2"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List a wallet's transactions",
        "tags": [
          "wallets"
        ]
      }
    },
    "/wallets/{walletId}/transactions/{transactionId}": {
      "get": {
        "description": "Your organization's own wallets, and its locations' if it has any. Never a linked dealer's. A wallet or transaction outside your organization returns 404.",
        "operationId": "getWalletTransactionV2",
        "parameters": [
          {
            "name": "walletId",
            "required": true,
            "in": "path",
            "description": "Wallet id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transactionId",
            "required": true,
            "in": "path",
            "description": "Transaction id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWalletTransactionResponseV2"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get one wallet transaction",
        "tags": [
          "wallets"
        ]
      }
    }
  },
  "info": {
    "title": "PrivateAuto Partner API (Beta)",
    "description": "> **Beta.** Not all endpoints are fully tested and verified; use caution with production deployments.\n\n<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## Choosing an entry point\n\nThere are two ways to bring a seller to PrivateAuto. Which one fits depends on one question:\n**has your flow already produced a firm price?**\n\n| | Lead — `POST /v2/leads` | Offer — `POST /v2/offers` |\n|---|---|---|\n| Use it when | The seller has raised their hand, but there is no firm price yet | Your flow already produced a firm price, and the seller should go straight into a deal |\n| Examples | A \"sell us your car\" form; an appraisal tool that only shows a range | An instant-offer tool where the seller clicked Accept; a CRM user who agreed a price by phone |\n| What happens next | The dealer reviews the lead, prices it, and sends the offer | The seller gets a link, accepts the offer, and the deal opens |\n| Scope | `leads:write` | `deal-invites:write` |\n| Idempotency | `callerReferenceId` is required | `callerReferenceId` is optional, and recommended |\n| Webhooks | None yet — poll `GET /v2/leads?callerReferenceId=…` | `offer.*`, then `deal.*` and `document.*` once the deal opens |\n\n`POST /v2/deal-invites` is the deprecated alias of `POST /v2/offers`: same request, same response,\nsame scope. It answers with `Deprecation: true` and a `Link` header naming `/v2/offers`. New\nintegrations should call `/v2/offers`.\n\n**Not yet available.** Plan around these rather than building toward them:\n\n- A lead does not link to the offer the dealer later sends, and there are no `lead.*` webhooks. You\n  can see a lead's status change, but not which offer or deal it became.\n- Offers are delivered by link — returned to you, and emailed if you ask. They are not sent by SMS.\n- There is no v2 route that looks a dealer up by a user's email.\n\n### Your organization\n\n\"Your organization\" below means everything your credential's own organization covers. A credential on\na dealer group's root covers the root and every one of the group's locations: it reads their vehicles,\ndeals and offers, and may act for any of them where a route names or reaches a location's record. One\nexception: `POST /v2/vehicles` always lists the vehicle under the credential's own organization, since\nthe request has no field to name a location. A credential on a location covers that location only,\nnever its parent or another location.\n\n### Who is who on an offer\n\n`POST /v2/offers` takes a `vin`, a `price` in US dollars (not cents), and the parties. Your account is\nalways one side of the offer. Say which side with `partnerSide` (`buyer` or `seller`), and name the\nother party under `counterparty` (`email`, optional `name`, and `sendLink: true` to have PrivateAuto\nemail them their link):\n\n```json\n{ \"vin\": \"1HGBH41JXMN109186\", \"price\": 18500, \"partnerSide\": \"buyer\",\n  \"counterparty\": { \"email\": \"seller@example.com\", \"sendLink\": true } }\n```\n\nTo start the deal for a dealership rather than your own organization, name it with\n`dealerOrganizationId`, or with `dealerExternalId` (your own identifier for it, as `GET /v2/dealers`\nshows). It must be your organization (a group root's credential may name one of its locations) or a\ndealership linked to your account, otherwise `403`\n`dealer_not_authorized`. The email on your own side (`buyerEmail` when you are the buyer) may name the\nuser acting for you, and must belong to that dealership.\n\n`amount` is the deprecated name for `price`. The older form still works: without `partnerSide`, the\nemails (`buyerEmail`, `sellerEmail`) decide which side you are on:\n\n| You send | Your side |\n|---|---|\n| `sellerEmail` only, naming someone outside your organization | You are the **buyer**; the email names the seller you are inviting |\n| `buyerEmail` only, naming someone outside your organization | You are the **seller**; the email names the buyer you are inviting |\n| Both, one of them a user in your organization, one of your group's locations, or a dealership linked to your account | That user is your side; the other email is the counterparty. A user of your own organization who can also reach its locations counts as your own organization |\n| Neither | You are the **buyer**; deliver the seller link yourself |\n\nBoth emails naming people outside your organization is rejected with `400`: the API does not start\ndeals where you are not a party. A new field sent with its old counterpart must agree, or the request\nis rejected with `400` (`price_conflict`, `counterparty_conflict`).\n\nIf the VIN is not already listed under your account, `year`, `make` and `model` are required with it.\nWithout `sendLink` (or, in the older form, `sellerSendLink` / `buyerSendLink`), deliver the returned\nlink yourself.\n\n### Worked examples\n\nEach example names the credential, the calls in order, and the webhooks to subscribe to. Scopes\nmarked *granted* are not part of the default set — ask PrivateAuto to add them (see\n[Scopes](#section/Scopes)). Managing webhook endpoints yourself needs `webhooks:manage`, and reading\nthe catalog or listing endpoints needs `webhooks:read`. Both are granted, so every \"subscribe to\" line\nbelow assumes them.\n\n#### Website vendor — \"sell us your car\" form\n\n- **Credential:** partner JWT or organization API key. **Scopes:** `leads:write` (default).\n- **Calls:** `POST /v2/leads` with the dealer's `organizationId`, the prospect under `contact`, the car\n  under `vehicle`, and your form submission id as `callerReferenceId`. Then\n  `GET /v2/leads?callerReferenceId=…` to follow its `status` (`new`, `contacted`, `qualified` or\n  `closed`).\n- **Webhooks:** none — there are no lead events yet.\n- You can submit leads for your own organization (a group root's credential also for each of its\n  locations), and for a dealership PrivateAuto has associated with your account for lead submission.\n  Any other `organizationId` is refused with `403`; a location's credential cannot submit for its\n  parent or another location.\n\n#### Appraisal tool that shows a range\n\nThe same as the website vendor: a range is not a firm price, so send a lead and let the dealer price\nit. Put the appraised vehicle under `vehicle`, and the range in `contact.message`. When your tool produces a single number the seller accepts, it has become the instant-offer case\nbelow.\n\n#### Instant-offer platform — the seller clicked Accept\n\n- **Credential:** partner JWT or organization API key. **Scopes:** `deal-invites:write` (default);\n  `deals:read` and `documents:read` (default) to read the deal afterwards.\n- **Calls:**\n  1. `POST /v2/offers` with `vin`, `price`, `partnerSide: \"buyer\"`, the seller under `counterparty` with\n     `sendLink: true`, and your quote id as `callerReferenceId`. Store the returned `offerId` and `guid`;\n     `dealId` is `null`.\n  2. Wait for `deal.created`, or poll `GET /v2/deals?callerReferenceId=…`.\n  3. `GET /v2/deals/{dealId}` and `GET /v2/deals/{dealId}/documents` as the deal progresses.\n- **Webhooks:** `offer.accepted`, `offer.rejected`, `deal.created`, `document.completed`,\n  `deal.payment_initiated`, `deal.payment_acknowledged`, `deal.completed`, `deal.cancelled`,\n  `deal.expired`. See [Event sequences](#section/Webhooks) under Webhooks for the order they arrive in.\n- If you buy on behalf of dealers, name the dealership with `dealerExternalId` or\n  `dealerOrganizationId`, and send the dealer user's email as `buyerEmail`. The deal is started for that\n  dealership. A dealership becomes linked when it approves your OAuth application and that credential\n  is first used, or when PrivateAuto links it for you.\n\n#### CRM or DMS — a price agreed by phone\n\n- **Credential:** partner JWT or organization API key. **Scopes:** `deal-invites:write`, `deals:read`,\n  `documents:read`, `documents:write` (default); `deals:write` (granted) to confirm title or cancel from\n  your system.\n- **Calls:**\n  1. `POST /v2/offers` with the agreed `price`, `partnerSide` (`buyer` or `seller`), the customer under\n     `counterparty` with `sendLink: true`, and your CRM record id as `callerReferenceId`. Retrying with the same `callerReferenceId`, VIN and emails returns the original\n     offer and sends nothing twice.\n  2. `GET /v2/deals?callerReferenceId=…` to find the deal once the customer accepts.\n  3. `POST /v2/deals/{dealId}/documents` to attach your paperwork; `GET /v2/deals/{dealId}/documents`\n     to collect signed copies.\n  4. With `deals:write`: `POST /v2/deals/{dealId}/title/confirm`, `POST /v2/deals/{dealId}/cancel`.\n- **Webhooks:** `deal.*` and `document.*`; add `offer.*` to see declines and withdrawals before a deal\n  exists.\n\n#### Embedded widget on your website\n\n- **Credential:** your **publishable key** in the `X-PA-Widget-Key` header — no `Authorization`\n  header. Requests are accepted only from the website origins PrivateAuto has configured for your\n  account. **Scope:** `deal-invites:write` (default).\n- **Calls:** `POST /v2/offers/widget` from the browser. It takes the older body only: `amount` rather\n  than `price`, at most one of `buyerEmail` / `sellerEmail` to name the visitor, and no\n  `callerReferenceId`. `partnerSide`, `counterparty`, `dealerOrganizationId`, `dealerExternalId` and\n  `price` are rejected with `400`, because a publishable key cannot vouch for a side or a dealership. No\n  email is sent: show the returned link to the visitor.\n- **Limits:** 10 requests per minute per client IP.\n- **Webhooks:** subscribe from your server, as for `POST /v2/offers`.\n\n#### Sourcing or AI buying agent\n\n- **Credential:** partner JWT or organization API key. **Scopes:** `marketplace:search` (granted).\n- **Calls:** `GET /v2/marketplace/vehicles` to search every vehicle publicly listed for sale.\n- **Not yet available:** making an offer on a vehicle found this way. Search results do not identify\n  the seller, and `POST /v2/offers` starts its own transaction rather than reaching the seller of an\n  existing marketplace listing. Use `POST /v2/offers` only when your agent already has the seller's\n  email.\n\n#### Auction — dealer to dealer\n\n- **Credential:** partner JWT or organization API key. **Scopes:** `deal-invites:write` (default).\n- **Calls:** `POST /v2/offers` with `partnerSide`, the dealership you act for in `dealerExternalId` or\n  `dealerOrganizationId`, its user's email on your side (`buyerEmail` or `sellerEmail`), and the other\n  dealer under `counterparty`. This works when both dealerships are linked to your account: the one you\n  name is yours.\n- In the older form, without `partnerSide` or a named dealership, the emails decide: exactly **one** of\n  them may belong to your organization or a linked dealership. If both do, the request is rejected with\n  `400` and `code: ambiguous_dealership_both_parties`. A user who belongs to several linked dealerships\n  is rejected with `ambiguous_dealership_multiple_orgs`; name the dealership to resolve either.\n- **Webhooks:** as for the instant-offer platform.\n\n#### Read-only reporting for a dealer (OAuth)\n\n- **Credential:** an OAuth token the dealer approved (see [Authentication](#section/Authentication)).\n  It holds at most `deals:read` and `vehicles:read`, and reads the dealer's organization and its\n  locations.\n- **Calls:** `GET /v2/deals`, `GET /v2/offers`, `GET /v2/vehicles`, then the single-record reads for\n  detail. `GET /v2/me` confirms the token works and shows the scopes it holds, but it reports your\n  partner identity, not the dealer's organization.\n- **Webhooks:** a delegated token cannot manage webhooks. With your own credential, subscribe to\n  `dealer.linked` and `dealer.unlinked` to learn when a dealer's approval takes effect or is revoked.\n  Deal, offer and vehicle events for the dealer's own activity are not delivered to you: poll the reads.\n\n## Identifiers\n\nFour identifiers follow an offer from the moment you send it to the closed deal. Store all four.\n\n| Identifier | What it is | Where it appears | When it is set |\n|---|---|---|---|\n| `offerId` | PrivateAuto's id for the offer | `POST /v2/offers` response (always); `id` on `GET /v2/offers/{offerId}` and on `offer.*` webhooks; `offerId` on a deal (the deal's most recent offer) | When you send the offer |\n| `dealId` | PrivateAuto's id for the deal | `POST /v2/offers` response; `id` on `GET /v2/deals/{dealId}` and on `deal.*` webhooks; `dealId` on document webhooks | **`null` until the seller accepts the offer.** It appears on the `deal.created` webhook, and a repeat of `POST /v2/offers` with the same `callerReferenceId` returns it once the deal exists |\n| `guid` | A stable handle for the transaction, safe to log and share across your systems | `POST /v2/offers` response; offers and deals (reads and webhooks) | When you send the offer. The deal opened from that offer carries the **same** `guid` |\n| `callerReferenceId` | **Your** reference — a quote, CRM record or form submission id | Echoed on the `POST /v2/offers` response, on the offer and deal reads, and on their webhooks; filter `GET /v2/offers` and `GET /v2/deals` by it | When you send it. `null` when you sent none, and always `null` on records another partner started |\n\nRules that follow from this:\n\n- **Branch on `dealId` being `null`.** An offer is not a deal. Do not fetch `/v2/deals/{dealId}` with\n  an `offerId` — it returns `404`.\n- **Use `guid` to join an offer to its deal** if you missed `deal.created`: both carry it.\n- **`callerReferenceId` makes `POST /v2/offers` safe to retry.** Sent again with the same VIN, buyer\n  email and seller email, it returns the original offer and changes nothing — no terms rewritten, no\n  email sent. Sent with a different VIN or emails, it is rejected with `409` and\n  `error: duplicate_reference`, carrying the existing `offerId` and a `redirectUrl` (the generic error\n  page in the user's app, safe to send them to). It is printable ASCII with no spaces,\n  1–128 characters, unique within your account.\n\nLeads have their own pair: `POST /v2/leads` returns a `leadId`, and its required `callerReferenceId`\nis the key for `GET /v2/leads`. A lead's ids are not linked to any offer or deal.\n\n## Quickstart\n\n1. **Get a Sandbox credential.** Ask PrivateAuto for a Sandbox partner secret or organization API key.\n   Build against the [Sandbox](#section/Sandbox) first.\n\n2. **Check who you are.** `GET /v2/me` needs no scope, so it is the cheapest way to prove the\n   credential works and to see what it may do:\n\n   ```bash\n   curl \"https://partner-api.padev.xyz/v2/me\" \\\n     -H \"Authorization: Bearer $CREDENTIAL\"\n   ```\n\n   ```json\n   {\n     \"partnerId\": \"acme-motors\",\n     \"name\": \"Acme Motors\",\n     \"organizationId\": \"663a1f4d6fae0c003456abcd\",\n     \"scopes\": [\"deals:read\", \"vehicles:read\", \"documents:read\", \"documents:write\", \"deal-invites:write\", \"leads:write\"],\n     \"apiVersion\": \"2.0.0\"\n   }\n   ```\n\n   Check `scopes` at startup, so a missing scope fails loudly there rather than as a `403` later.\n\n3. **Make your first call.** Pick the entry point that fits your flow (see\n   [Choosing an entry point](#section/Choosing-an-entry-point)):\n\n   ```bash\n   # A lead: no firm price yet\n   curl -X POST \"https://partner-api.padev.xyz/v2/leads\" \\\n     -H \"Authorization: Bearer $CREDENTIAL\" -H \"Content-Type: application/json\" \\\n     -d '{\"callerReferenceId\":\"LDR-0001\",\"organizationId\":\"663a1f4d6fae0c003456abcd\",\n          \"contact\":{\"name\":\"Jane Smith\",\"email\":\"jane@example.com\"},\n          \"vehicle\":{\"vin\":\"1HGBH41JXMN109186\",\"year\":2019,\"make\":\"Honda\",\"model\":\"Accord\"}}'\n\n   # An offer: the price is agreed\n   curl -X POST \"https://partner-api.padev.xyz/v2/offers\" \\\n     -H \"Authorization: Bearer $CREDENTIAL\" -H \"Content-Type: application/json\" \\\n     -d '{\"vin\":\"1HGBH41JXMN109186\",\"year\":2019,\"make\":\"Honda\",\"model\":\"Accord\",\n          \"price\":18500,\"partnerSide\":\"buyer\",\"counterparty\":{\"email\":\"seller@example.com\"},\n          \"callerReferenceId\":\"QUOTE-0001\"}'\n   ```\n\n4. **Subscribe to events.** With `webhooks:manage`, register an endpoint, set its subscriptions, send\n   it a test event, then verify it — see [Webhooks](#section/Webhooks).\n\nRequests are JSON. A field the endpoint does not define is rejected with `400`, so send only\ndocumented fields.\n\n## Sandbox\n\nThe Sandbox is PrivateAuto's test environment. Build and test your integration there before you\npoint it at production.\n\n| Environment | API host |\n|---|---|\n| Sandbox | `https://partner-api.padev.xyz` |\n| Production | `https://partner-api.privateauto.com` |\n\nSetting up:\n\n1. **Ask PrivateAuto for Sandbox credentials** and for any *granted* scopes you need (see\n   [Scopes](#section/Scopes)). Confirm them with `GET /v2/me`.\n2. **Use your own test addresses** for the counterparty and for `buyerEmail` / `sellerEmail`. An offer\n   with `counterparty.sendLink` (or `sellerSendLink` / `buyerSendLink`) set can send a real email to the\n   address you give.\n3. **Register a webhook endpoint** that the Sandbox can reach over public HTTPS. Private and internal\n   addresses are rejected in every environment.\n4. **Check what the Sandbox serves** rather than assuming it matches production, or this page. The\n   documentation can describe a newer build than the environment in front of you — see\n   [Availability by release](#section/Webhooks). `GET /api/docs-json` returns the spec the environment\n   is actually serving.\n\nIds, endpoints and webhook subscriptions do not carry over between the Sandbox and production: set\nthem up again when you go live. If you use OAuth, the authorization and token endpoints also differ\nbetween the two — take each from what PrivateAuto sends you.\n\nOffer actions on an existing deal (`POST /v2/deals/{dealId}/offers` and its `accept`, `decline` and\n`withdraw` routes) answer `503` with `code: deal_first_not_enabled` in an environment where they are\nnot live yet. Check before relying on them in either environment.\n\n## Authentication\n\nEvery v2 request carries a credential in the `Authorization` header. Unlike v1, **v2 takes your\nidentity from the credential itself** — there is no `{partnerId}` in any v2 path, and nothing you\nsend in the URL or body changes which partner you are.\n\nThree credential types are supported. OAuth is **dealer-delegated** and works differently from the\nother two — read its section before building against it.\n\n| Credential | Send as | Status |\n|---|---|---|\n| Partner JWT (HMAC) | `Authorization: Bearer <jwt>` | Available — what v1 partners already use |\n| Organization API key | `Authorization: Bearer <key>` | Available |\n| OAuth (dealer-approved) | `Authorization: Bearer <jwt>` | Available — **read-only**, and enabled per integration |\n\nBoth available types resolve to the same partner identity and the same scopes, so an integration\ncan move from one to the other without changing a single request.\n\n### Partner JWT (HMAC)\n\nThe token must be a **HS256, HS384 or HS512 JWT** signed with your partner shared secret, which\nPrivateAuto provides during onboarding.\n\nYour shared secret is delivered base64-encoded — decode it to a UTF-8 string before signing. The\npayload must include `p` (your partner identifier) and **must** include `exp`; we recommend five\nminutes or less.\n\n> `exp` is required in v2. v1 accepts a token without one, which is a bearer credential that never\n> ages out. If your v1 signing code omits `exp`, add it before you migrate — everything else about\n> your tokens is unchanged.\n\nThe signing algorithm is pinned to the one on your partner record, not to the one in the token\nheader, so changing `alg` in a token does not change how it is verified.\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### Organization API key\n\nAn API key is an opaque string — not a JWT — issued by PrivateAuto for your organization. Send it\nas the bearer value exactly as delivered; there is nothing to sign and no expiry to manage per\nrequest:\n\n```bash\nKEY=$(cat /path/to/your/api-key)   # keep it out of your shell history\ncurl \"https://partner-api.privateauto.com/v2/me\" \\\n  -H \"Authorization: Bearer $KEY\"\n```\n\nThree things are worth knowing before you choose it over a JWT:\n\n- **Scopes are intersected on every request.** A key carries its own permissions, and what it may\n  actually do is those permissions intersected with your partner grant, recalculated on every\n  request. A key issued while you held a wider grant does not keep the wider access. A key issued\n  with no permissions authenticates successfully and reaches only routes that require no scope —\n  `GET /v2/me` will show you an empty `scopes` array rather than failing.\n- **Revocation is not instantaneous.** A successful validation is trusted for up to 60 seconds, so\n  a revoked key may keep working for that long. Treat it as a minute, not as immediate.\n- **Keys are long-lived.** They do not rotate themselves. Rotate on your own schedule, and ask\n  PrivateAuto to revoke the old key once the new one is in service.\n\n### OAuth (dealer-delegated)\n\nThe other two credentials are **you, acting as yourself**. OAuth is different: a **dealer authorises\nyour application to read their data**, and your token acts on that dealer's behalf. Use it when your\nproduct works with dealers who are not you.\n\n**It is enabled per integration, not self-service.** PrivateAuto registers your OAuth application\nagainst your partner account first. Until that exists, a token from it is rejected with the same\n`401` as any other unknown credential — there is nothing to probe, so if you are building against\nthis, talk to your PrivateAuto contact before you start.\n\n#### Getting a dealer connected\n\nPrivateAuto registers your application and gives you four things: a **client id**, the **redirect\nURI** we registered for you, and the environment's **authorization** and **token** endpoints. Those\nendpoints are not on the API host — they belong to the identity provider, and they differ between\nthe Sandbox and production, so take them from what we send you rather than deriving them from the API URL.\n\nThe flow is standard OAuth 2.0 **authorization code with PKCE**. Your application is a public client:\nthere is no client secret, and PKCE is what takes its place, so it is required rather than optional.\n\n1. **Send the dealer to the authorization endpoint** with your `client_id`, your registered\n   `redirect_uri`, `response_type=code`, a `state` value you generate, and a PKCE\n   `code_challenge` (with `code_challenge_method=S256`).\n2. **The dealer signs in and chooses an organization.** If they belong to more than one they are\n   shown a picker and pick one — you do not choose for them, and you cannot pass one in. Whichever\n   they choose is the organization your token will read.\n3. **They approve your application**, and we redirect back to your `redirect_uri` with `code` and\n   your `state`. **Check the `state` matches** before going further.\n4. **Exchange the code** at the token endpoint for an access token and a refresh token, sending the\n   `code_verifier` that matches the challenge from step 1.\n5. **Call the API** with `Authorization: Bearer <access token>`, and confirm with `GET /v2/me` that\n   the scopes are what you expect before running real traffic.\n\nTwo things that catch people out:\n\n- **Keep the `code_verifier` for the exchange.** It is generated in step 1 and needed in step 4. If\n  your callback handler runs in a different process from the one that built the authorization URL,\n  the verifier has to survive that hop — and an authorization code is single-use and short-lived, so\n  losing it means sending the dealer through consent again.\n- **Refresh tokens rotate.** Every refresh returns a *new* refresh token and invalidates the one you\n  sent. Store the new one before you use the access token, or the next refresh fails and the dealer\n  has to reconnect.\n\n#### What a delegated token can do\n\n**Read-only, and narrower than your own credential.** A delegated token may hold only `deals:read`\nand `vehicles:read`, intersected with what your partner account already holds — it can never gain a\ncapability you do not have, and it can never write, publish, manage dealers or manage webhooks. If\nyou need to act on a dealer's behalf beyond reading, that is a conversation to have with us rather\nthan a scope to request.\n\nCheck `GET /v2/me` as always: it reports the scopes the token actually holds, which for a delegated\ncredential will be a subset of your account's.\n\n#### Whose data it reads\n\nThe dealer's, not yours. When a dealer approves your application they choose an organization, and\nyour token reads **that organization and its locations** — a dealer group, not a single rooftop,\nbecause that is the unit the consent screen presents. Your own inventory and deals are not visible\nthrough a delegated token; use your partner JWT or API key for those.\n\n#### Revocation — read this before you design your token handling\n\nA dealer can withdraw consent at any time. When they do:\n\n- **Refreshing stops immediately.** Your next refresh exchange fails.\n- **An access token already issued keeps working until it expires**, which can be up to 24 hours.\n\nThat is a property of the identity provider, not a choice we made, and it is why the recommendation\nbelow matters: **refresh often and treat the access token as short-lived**, even though its `exp`\nsays otherwise. Refresh tokens rotate on every exchange, so always store the new one and discard the\nold.\n\nPrivateAuto can also disable your OAuth client outright, which takes effect on the next request\nrather than at token expiry. We will do that if a dealer reports a problem.\n\n### Making an authenticated request\n\n```bash\ncurl \"https://partner-api.privateauto.com/v2/me\" \\\n  -H \"Authorization: Bearer $CREDENTIAL\"\n```\n\n`GET /v2/me` takes no scope and is the cheapest way to confirm a credential works. It reports your\npartner id, the organization the credential acts as, and **every scope it holds** — check that at\nstartup, so a missing scope fails loudly at boot rather than as a `403` in production.\n\n### When authentication fails\n\n- **`401`** — the credential was rejected. The body is deliberately identical for every cause\n  (unknown partner, bad signature, missing or past `exp`, unknown or revoked key, a key belonging\n  to no partner), because a response that told them apart would let a caller enumerate partners and\n  organizations. Do not parse it; re-check the credential itself.\n- **`403`** — the credential is valid but lacks the scope the route requires. Compare what\n  `GET /v2/me` reports against the scope named on the endpoint.\n- **`503` with `Retry-After`** — credential verification is temporarily unavailable. This is **not**\n  a verdict on your credential and rotating it will not help. Back off for the advertised number of\n  seconds and retry.\n\nProduction host: `https://partner-api.privateauto.com`. Sandbox host: `https://partner-api.padev.xyz` (see [Sandbox](#section/Sandbox)).\n\n## Scopes\n\nEvery v2 route names the scope it requires; a credential without it gets `403` with\n`Missing required scope: <scope>`. `GET /v2/me` requires none and lists the scopes your credential\nholds.\n\n**Default** scopes are what an account has when PrivateAuto has not set an explicit list for it — the\nsame capabilities v1 offers. **Granted** scopes are never part of the default: ask PrivateAuto to add\nthem. Once your account has an explicit list, that list is exactly what you hold.\n\n| Scope | Unlocks | |\n|---|---|---|\n| `deals:read` | `GET /v2/deals`, `GET /v2/deals/{dealId}`, `GET /v2/offers`, `GET /v2/offers/{offerId}`. Subscribing to `deal.*`, `offer.*` and `dealer.*` events | Default |\n| `deals:write` | `POST /v2/deals/{dealId}/title/confirm`, `POST /v2/deals/{dealId}/services`, `POST /v2/deals/{dealId}/cancel` | Granted |\n| `deal-invites:write` | `POST /v2/offers`, `POST /v2/offers/widget`, and their deprecated aliases `POST /v2/deal-invites` and `POST /v2/deal-invites/widget` | Default |\n| `offers:write` | Acting on the live offer of an existing deal: `POST /v2/deals/{dealId}/offers` (counter), and `.../accept`, `.../decline`, `.../withdraw` | Granted |\n| `leads:write` | `POST /v2/leads` and `GET /v2/leads` — the lookup needs it too | Default |\n| `vehicles:read` | `GET /v2/vehicles`, `GET /v2/vehicles/{vehicleId}`, `GET /v2/vehicles/{vehicleId}/photos`. Subscribing to `listing.*` events | Default |\n| `vehicles:write` | `POST /v2/vehicles`; changing the price, taking a vehicle off the market and putting it back; adding, removing and ordering photos | Granted |\n| `vehicles:publish` | `POST /v2/vehicles/{vehicleId}/listing/publish` — puts a vehicle on the public marketplace, which is billable | Granted |\n| `marketplace:search` | `GET /v2/marketplace/vehicles` | Granted |\n| `documents:read` | `GET /v2/deals/{dealId}/documents`, `GET /v2/documents/{documentId}`, `GET /v2/generated-documents/{documentId}`. Subscribing to `document.*` events | Default |\n| `documents:write` | `POST /v2/deals/{dealId}/documents`, `DELETE /v2/documents/{documentId}` | Default |\n| `webhooks:read` | `GET /v2/webhooks/endpoints`, `GET /v2/webhooks/endpoints/{endpointId}`, `GET /v2/webhooks/catalog` | Granted |\n| `webhooks:manage` | Registering, changing, verifying, testing, pausing and removing endpoints; rotating secrets; editing subscriptions; `GET /v2/webhooks/deliveries` | Granted |\n| `dealers:manage` | `GET /v2/dealers`, `GET /v2/dealers/{externalId}` | Granted |\n| `reports:read` | `GET /v2/reports`, `GET /v2/reports/{shareId}` | Granted |\n| `wallet:read` | `GET /v2/wallets` and the wallet and transaction reads under it | Granted |\n\n`GET /v2/me` can also list `dealers:lookup`. No v2 route uses it.\n\nWhat a credential actually holds depends on its type as well as your account:\n\n- **Partner JWT** — your account's scopes.\n- **Organization API key** — the key's own permissions intersected with your account's scopes,\n  recalculated on every request.\n- **OAuth (dealer-delegated)** — at most `deals:read` and `vehicles:read`, intersected with your\n  account's scopes.\n- **Widget publishable key** — used only by `POST /v2/offers/widget`, which checks your account\n  holds `deal-invites:write`.\n\n## Examples\n\nAbbreviated: each endpoint's reference below lists every field.\n\n### Send an offer\n\n`POST /v2/offers` — you are buying, so the counterparty is the seller:\n\n```json\n{\n  \"vin\": \"1HGBH41JXMN109186\",\n  \"year\": 2019,\n  \"make\": \"Honda\",\n  \"model\": \"Accord\",\n  \"price\": 18500,\n  \"partnerSide\": \"buyer\",\n  \"counterparty\": { \"email\": \"seller@example.com\", \"name\": \"John Doe\", \"sendLink\": true },\n  \"callerReferenceId\": \"QUOTE-0001\"\n}\n```\n\n`201 Created`:\n\n```json\n{\n  \"offerId\": \"64a1f2e3b5c8d90012345678\",\n  \"dealId\": null,\n  \"guid\": \"b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8\",\n  \"callerReferenceId\": \"QUOTE-0001\",\n  \"buyerLink\": \"https://…\",\n  \"sellerLink\": \"https://…\"\n}\n```\n\nThe same request sent again returns this same body, with `dealId` filled in once the seller has\naccepted. The same `callerReferenceId` with a different VIN or email returns `409`:\n\n```json\n{\n  \"error\": \"duplicate_reference\",\n  \"message\": \"callerReferenceId is already used for an invitation with a different VIN, buyer email or seller email\",\n  \"offerId\": \"64a1f2e3b5c8d90012345678\",\n  \"redirectUrl\": \"https://app.privateauto.com/error\"\n}\n```\n\n`redirectUrl` is the generic error page in the user's PrivateAuto or DealNow app (matching your link\nplatform). It is public and carries no token, so you can send the user there instead of showing the error.\n\n### Read the deal once the seller accepts\n\n`GET /v2/deals?callerReferenceId=QUOTE-0001`, or `GET /v2/deals/{dealId}` with the id from\n`deal.created`:\n\n```json\n{\n  \"id\": \"64a1f2e3b5c8d90012345679\",\n  \"guid\": \"b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8\",\n  \"status\": \"active\",\n  \"offerId\": \"64a1f2e3b5c8d90012345678\",\n  \"currentOfferStatus\": \"accepted\",\n  \"callerReferenceId\": \"QUOTE-0001\",\n  \"amount\": 18500,\n  \"closingStatus\": \"none\",\n  \"documentsStatus\": \"pending\"\n}\n```\n\nList reads are paged with `_page` (from 0) and `_limit`, and return `{ \"data\": [...], \"_meta\": { \"page\",\n\"limit\", \"total\", \"hasMore\" } }`.\n\n### Submit a lead\n\n`POST /v2/leads`:\n\n```json\n{\n  \"callerReferenceId\": \"LDR-0001\",\n  \"organizationId\": \"663a1f4d6fae0c003456abcd\",\n  \"leadCode\": \"TRADE_IN\",\n  \"contact\": { \"name\": \"Jane Smith\", \"email\": \"jane@example.com\", \"phone\": \"555-867-5309\" },\n  \"vehicle\": { \"vin\": \"1HGBH41JXMN109186\", \"year\": 2019, \"make\": \"Honda\", \"model\": \"Accord\", \"mileage\": 42000 }\n}\n```\n\n`201 Created`:\n\n```json\n{\n  \"leadId\": \"663c3f4d6fae0c003456cdef\",\n  \"callerReferenceId\": \"LDR-0001\",\n  \"status\": \"new\",\n  \"createdAt\": \"2026-11-13T14:22:00.000Z\"\n}\n```\n\nSending the same `callerReferenceId` again returns `409` with the lead you already created:\n\n```json\n{ \"error\": \"duplicate_reference\", \"leadId\": \"663c3f4d6fae0c003456cdef\", \"callerReferenceId\": \"LDR-0001\" }\n```\n\n### A webhook delivery\n\n`deal.created`, as posted to your endpoint:\n\n```json\n{\n  \"id\": \"64a1f2e3b5c8d90012345679\",\n  \"eventId\": \"a2f1e9c4b7d8…\",\n  \"eventKey\": \"…\",\n  \"status\": \"active\",\n  \"guid\": \"b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8\",\n  \"amount\": 18500,\n  \"buyerId\": \"64a1f2e3b5c8d90012340001\",\n  \"sellerId\": \"64a1f2e3b5c8d90012340002\",\n  \"callerReferenceId\": \"QUOTE-0001\"\n}\n```\n\n## Status values\n\nOffer and deal statuses are closed lists: a value outside the list is reported as `null` rather than\npassed through. Lead and listing statuses are reported as stored. Either way, treat a value you do not\nrecognise as something to log, not to fail on.\n\n**Offer** — `status` on `GET /v2/offers`, and `currentOfferStatus` on a deal:\n\n| Value | Meaning |\n|---|---|\n| `pending` | On the table, waiting for the other side |\n| `accepted` | Accepted — this is the offer that opened the deal |\n| `countered` | Replaced by a counter-offer |\n| `declined` | Declined by the side it was sent to. The event is `offer.rejected` |\n| `deleted` | Withdrawn by the side that made it. The event is `offer.cancelled` |\n\n**Deal** — `status` on `GET /v2/deals`:\n\n| Value | Meaning |\n|---|---|\n| `pending` | Created, not yet active |\n| `active` | In progress: the parties are working through title, documents and payment |\n| `sold` | Completed. The event is `deal.completed` |\n| `cancelled` | Cancelled by a party. The event is `deal.cancelled` |\n| `expired` | Lapsed without completing. The event is `deal.expired` |\n\nInside an active deal, `closingStatus` tracks the money — `none`, `ready`, `initiated`,\n`acknowledged` — and `documentsStatus` the paperwork — `empty`, `pending`, `complete`. Each party's\n`status` is `invited`, `joined` or `readyToClose`.\n\n**Lead** — `status` on `POST /v2/leads` and `GET /v2/leads`:\n\n| Value | Meaning |\n|---|---|\n| `new` | Received; every lead starts here |\n| `contacted` | The dealer has contacted the prospect |\n| `qualified` | The dealer has qualified the lead |\n| `closed` | The dealer has closed the lead |\n\n**Vehicle listing** — `listing.status` on `GET /v2/vehicles`:\n\n| Value | Meaning |\n|---|---|\n| `pending` | Created but not on the marketplace. `POST /v2/vehicles` creates listings here, and reactivating returns one here |\n| `live` | Published on the marketplace |\n| `sold` | Sold |\n| `deactivated` | Taken off the market |\n| `expired` | Lapsed. Reactivate it to list it again |\n| `expiredGrace` | Lapsed, like `expired`, and handled the same way: reactivate it to list it again |\n| `purchased` | A vehicle your organization bought through PrivateAuto, rather than one you listed. Filter with `ownership=purchased` |\n| `removed` | Taken down by your organization. Returned when you omit `ownership`, left out by `ownership=listed`. Filter with `status=removed` and no `ownership` |\n\n## Errors\n\nErrors are JSON. Most have the shape `{ \"statusCode\": 400, \"message\": \"…\", \"error\": \"Bad Request\" }`,\nwhere `message` is a string, or an array of strings for a request that failed validation. Where a\nfailure has a machine-readable code, it is in **`code`** or — for the older codes marked *(error)* in\nthe table — in **`error`**. Branch on the code, never on `message` text.\n\n| Status | Meaning |\n|---|---|\n| `400` | The request is malformed: a missing or invalid field, a field the endpoint does not define, or one of the `400` codes below |\n| `401` | The credential was rejected. The body is identical for every cause — see [Authentication](#section/Authentication) |\n| `402` | The dealership has no active PrivateAuto business subscription: publishing a vehicle, or starting an offer with `POST /v2/offers` — see `subscription_inactive` below |\n| `403` | The credential is valid but lacks the route's scope (`Missing required scope: …`), is not allowed to act for the organization named in the request, or the dealership has not finished payment setup (`onboarding_incomplete` below) |\n| `404` | The record does not exist **or is not visible to you**. The two are deliberately indistinguishable. A route your environment does not serve also returns `404` |\n| `409` | The request conflicts with the record's current state — see the codes below |\n| `413` | An uploaded document is too large |\n| `429` | A rate limit was hit — see [Rate limits](#section/Rate-limits) |\n| `503` | Temporarily unavailable. Honour `Retry-After` when present, and retry |\n\n| Code | Status | When |\n|---|---|---|\n| `ambiguous_dealership_both_parties` | 400 | `POST /v2/offers` without `partnerSide` or a named dealership: both emails belong to dealerships linked to your account. `message` names them |\n| `ambiguous_dealership_multiple_orgs` | 400 | `POST /v2/offers`: the email on your side belongs to a user of several linked dealerships. Name the dealership with `dealerOrganizationId` or `dealerExternalId` |\n| `price_conflict` | 400 | `POST /v2/offers`: `price` and the deprecated `amount` both sent, with different values |\n| `counterparty_conflict` | 400 | `POST /v2/offers`: `counterparty` sent without `partnerSide`, or disagreeing with the old field for the same party (`buyerEmail`, `buyerName`, `buyerSendLink` when you are the seller) |\n| `dealer_attribution_conflict` | 400 | `POST /v2/offers`: `dealerOrganizationId` and `dealerExternalId` name different dealerships |\n| `unknown_event` | 400 | Subscribing to an event name that does not exist. `events` lists them |\n| `invalid_url`, `insecure_transport`, `credentials_in_url`, `private_destination`, `unresolvable_host` | 400 | A webhook endpoint URL that is not a public HTTPS address |\n| `passcode_required` | 401 | Reading a report link that is protected by a passcode |\n| `subscription_inactive` *(error)* | 402 | `POST /v2/vehicles/{vehicleId}/listing/publish` for a dealership without an active subscription (for a location, neither it nor its group's root has one; the message names the root's status). Also `POST /v2/offers` and `POST /v2/offers/widget` when the dealership the offer is made for (your own organization, or the linked dealership you act for) has no active business subscription. The body can carry `redirectUrl`, the page where the dealership fixes it |\n| `onboarding_incomplete` *(error)* | 403 | `POST /v2/offers` and `POST /v2/offers/widget` when the dealership the offer is made for has not finished payment setup. The body can carry `redirectUrl`, the page where the dealership fixes it |\n| `dealer_not_authorized` | 403 | `POST /v2/offers`: the dealership named by `dealerOrganizationId` or `dealerExternalId` is not your organization (or, for a group root's credential, one of its locations) or linked to your account. An unknown `dealerExternalId` gets the same answer |\n| `event_not_entitled` | 403 | Subscribing to events your scopes do not cover. `events` lists them |\n| `duplicate_reference` *(error)* | 409 | A `callerReferenceId` reused with different content: on `POST /v2/offers` (carries `offerId`, and `redirectUrl`, the generic error page in the user's PrivateAuto or DealNow app, safe to send them to), `POST /v2/leads` (carries `leadId`; any reuse) or a document upload (a different file) |\n| `competing_active_deal` | 409 | Accepting an offer when another deal on the same vehicle is already active |\n| `invalid_transition` | 409 | Countering, accepting, declining or withdrawing an offer that is not in a state that allows it |\n| `deal_not_cancellable` | 409 | Cancelling a deal that can no longer be cancelled |\n| `deal_not_uploadable` *(error)* | 409 | Uploading a document to a cancelled or expired deal |\n| `document_acted_on` *(error)* | 409 | Removing a document that has already been signed or acknowledged |\n| `photo_set_mismatch` *(error)* | 409 | Reordering photos with a list that is not exactly the vehicle's current photos |\n| `endpoint_exists` | 409 | Registering a webhook URL you have already registered, or changing an endpoint to one |\n| `endpoint_limit_reached` | 409 | Registering more than 10 webhook endpoints |\n| `endpoint_unverified` | 409 | Enabling or disabling an endpoint that has never been verified |\n| `no_challenge_outstanding`, `challenge_superseded` | 409 | Verifying an endpoint with no current challenge, or whose challenge changed mid-verification. Request verification again |\n| `rate_limit_exceeded` *(error)* | 429 | `POST /v2/leads`, or webhook `verify`/`test`. `retryAfterMs` says how long to wait |\n| `auth_unavailable` | 503 | Credential checking is temporarily unavailable — not a verdict on your credential. Sent with `Retry-After` |\n| `deal_first_not_enabled` | 503 | Offer actions on an existing deal are not live in this environment yet |\n\n## Rate limits\n\n| Route | Limit | Counted per |\n|---|---|---|\n| `POST /v2/leads` | **60 per minute** by default; PrivateAuto can set a different limit for your account | Your partner account — v1 and v2 lead submissions share one window |\n| `POST /v2/offers`, `POST /v2/deal-invites` | No route-specific limit | — |\n| `POST /v2/offers/widget`, `POST /v2/deal-invites/widget` | **10 per minute** | Client IP, per route |\n| Webhook `POST .../verify` and `POST .../test` together | **10 per minute** | Your partner account |\n| `GET /v2/reports`, `GET /v2/reports/{shareId}` | **30 per minute** | Client IP |\n\nEach limit applies over a one-minute window. `POST /v2/leads` and webhook `verify`/`test` send\n`X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (epoch seconds at which capacity\nnext returns) — `verify`/`test` on every response, leads **only on success**. Their `429` body carries\n`retryAfterMs`, the wait in milliseconds before capacity returns; pace retries off that.\n\n```json\n{ \"statusCode\": 429, \"error\": \"rate_limit_exceeded\", \"message\": \"Rate limit exceeded: 60 requests per minute\", \"retryAfterMs\": 41250 }\n```\n\nThe counters are kept by each API server rather than shared between them, so you may occasionally\nget more than the stated limit through. Design for the stated number.\n\n`POST /v2/offers` having no specific limit is not an invitation to burst: send each offer once, and use\n`callerReferenceId` so a retry is safe rather than sending a second offer.\n\n## Webhooks\n\nPrivateAuto posts an event to your server whenever something happens to an offer, deal, document,\nvehicle listing or dealer link that your integration can see.\n\nIn v2 you set webhooks up yourself: register an endpoint, choose the events it receives, verify it,\nand rotate its secret through `/v2/webhooks/*`. Listing endpoints and reading the catalog need the\n`webhooks:read` scope; managing endpoints and reading the delivery log need `webhooks:manage`. Neither\nis a default scope — ask PrivateAuto to grant both (see [Scopes](#section/Scopes)).\n\n> **Already receiving webhooks from a v1 integration?** That configuration keeps delivering until you\n> verify a v2 endpoint. Read [Coming from v1](#section/Webhooks) under Configuration before you start.\n\n> **Reading this against a specific environment?** This page can describe a newer build than the one\n> you are calling. See [Availability by release](#section/Webhooks) for how to check.\n\n### Configuration\n\n| Operation | Endpoint |\n|---|---|\n| Register an endpoint | `POST /v2/webhooks/endpoints` |\n| List / inspect | `GET /v2/webhooks/endpoints` · `GET /v2/webhooks/endpoints/{endpointId}` |\n| Update | `PATCH /v2/webhooks/endpoints/{endpointId}` |\n| Remove | `DELETE /v2/webhooks/endpoints/{endpointId}` |\n| Pause / resume delivery | `POST .../disable` · `POST .../enable` |\n| Issue a new signing secret | `POST .../rotate-secret` |\n| Prove ownership | `POST .../verify` |\n| Send a synthetic event | `POST .../test` |\n| See what was delivered | `GET /v2/webhooks/deliveries` · `GET /v2/webhooks/deliveries/{logId}` |\n\nSubscriptions are managed per endpoint:\n\n| Operation | Endpoint |\n|---|---|\n| Replace the whole set | `PUT /v2/webhooks/endpoints/{endpointId}/subscriptions` |\n| Add to the set | `POST /v2/webhooks/endpoints/{endpointId}/subscriptions` |\n| Remove one event | `DELETE /v2/webhooks/endpoints/{endpointId}/subscriptions/{event}` |\n| Clear every subscription | `DELETE /v2/webhooks/endpoints/{endpointId}/subscriptions` |\n\nReading endpoints and the catalog needs `webhooks:read`; everything else here, including the delivery\nlog, needs `webhooks:manage`.\n\nYou may register up to 10 endpoints, each with its own subscription set and its own secret — a\ndelivery fans out to every active endpoint subscribed to that event. Each delivery carries its own\nidempotency identifier, so two endpoints receiving the same event are two distinct deliveries.\n\n**Setting up an endpoint, in order:**\n\n1. `POST /v2/webhooks/endpoints` with your URL. It starts `unverified`, and only `active` endpoints\n   receive events.\n2. Set its subscriptions.\n3. `POST .../test` to confirm it accepts a delivery and your signature check passes.\n4. `POST .../verify` to prove you control the URL. The endpoint becomes `active`.\n\n#### Testing an endpoint\n\n`POST .../test` sends a synthetic `endpoint.test` event signed **exactly like a real\ndelivery** — the same `sha256=` signature, timestamp format and headers — so a receiver\nthat passes it will verify real traffic. It works on an `unverified` endpoint, which makes\nit the tool for working out why verification is failing.\n\n`verify` is different: the challenge is **unsigned**. It proves you control the URL, not\nthat your signature check works. Answer it with a 2xx whose body contains the `challenge`\nvalue.\n\n`verify` and `test` both make PrivateAuto call your URL, and together they are limited to\n**10 requests per minute** per partner. Beyond that they answer `429`; the\n`X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers say when\ncapacity returns.\n\n#### Rotating a signing secret\n\n`POST .../rotate-secret` returns a new secret once. Deliveries may be signed with the\nnew secret from the moment the call returns, and all of them are within 5 minutes.\n**None is signed with the old secret after `previousSecretExpiresAt`** — 15 minutes after\nthe call.\n\n- Your receiver must accept the new secret as soon as the call returns.\n- Load the secrets you accept from a store you read at request time (or hot-reload), so\n  that storing the new secret makes it live without a redeploy.\n- Keep accepting the old secret until `previousSecretExpiresAt`, then remove it.\n- A delivery rejected before your receiver accepts the new secret is recorded as failed\n  and retried on the usual schedule (1, 5 and 15 minutes); one that fails every retry is\n  listed under `GET /v2/webhooks/deliveries?status=dlq` for you to reconcile.\n\n#### What you may subscribe to\n\n`GET /v2/webhooks/catalog` returns exactly the events **your credential** may\nsubscribe to. Entitlement is derived from the scopes you already hold rather than\nmaintained as a separate list, so it cannot disagree with what you can read:\n\n| Event namespace | Requires |\n|---|---|\n| `deal.*`, `dealer.*`, `offer.*` | `deals:read` |\n| `listing.*` | `vehicles:read` |\n| `document.*` | `documents:read` |\n\n`*` subscribes to everything, and needs all three scopes. Subscribing to an event outside your scopes\nis rejected with `403` and `code: event_not_entitled`; an event name that does not exist, with `400`\nand `code: unknown_event`. Read the catalog rather than hardcoding a list — it is the authoritative\nanswer for your credential, and it is what the API enforces.\n\nUser events (`user.registered`) are **not subscribable in v2**: they carry a person's email address\nand name.\n\n#### Endpoint requirements\n\nYour endpoint URL must be public HTTPS. Private and internal addresses are rejected,\nincluding link-local metadata addresses, and the check is applied again at delivery\ntime rather than only at registration — a hostname that resolves publicly when you\nregister it and privately later does not become a way in.\n\n#### Coming from v1\n\nDelivery format, signature scheme, idempotency identifier and retry behaviour are\nunchanged — those belong to the delivery pipeline, not to the API version. Your\nexisting endpoint keeps receiving events until you deliberately migrate.\n\nEvent names are unchanged too, unless you opt in. A managed endpoint that copies your\nv1 list, wildcards included, receives the same names v1 sends. Only an endpoint that lists\na canonical name from **Deprecations** (for example `offer.declined`) receives that event\nunder the canonical name. Wildcard subscriptions move to the canonical names at a cut-over\ndate we will announce there. Your v1 configuration always receives the original names,\nincluding when delivery falls back to it because you no longer have an active managed\nendpoint.\n\nRouting is **either/or per partner**, never both: while you have no active managed\nendpoint you are served from your v1 configuration, and as soon as you have one\nyou are served from managed endpoints only. That is what stops a migrating partner\nreceiving everything twice.\n\n**Verification is the cutover, not registration.** A new endpoint starts\n`unverified`, and only `active` endpoints receive deliveries — so\n`POST /v2/webhooks/endpoints` on its own changes nothing. The moment you complete\n`POST .../verify`, that endpoint becomes active and **your v1 endpoint stops\nreceiving**.\n\nSo follow the setup order above, and note at step 2 that **subscriptions do not carry over.** Your v1\nevent list is separate configuration; a managed endpoint starts with only what you give it, so\nverifying with an empty or partial set silently narrows your feed.\n\nOne event cannot be carried across: **`user.registered` is not subscribable in v2**.\nIf you receive it today under your v1 configuration, verifying a managed endpoint ends it.\nRaise this with us before you migrate rather than after.\n\nTwo behaviours worth knowing because they are easy to be surprised by:\n\n- Disabling or deleting every managed endpoint puts you **back on the v1\n  destination**, because the fallback is chosen when no active endpoint exists.\n- That includes automatic disabling. An endpoint that fails enough consecutive\n  deliveries is disabled for you — and if it was your only one, delivery reverts to\n  your v1 endpoint rather than stopping. Watch\n  `GET /v2/webhooks/deliveries` after cutover; a silent return to the old\n  destination looks a lot like nothing having happened.\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| `*` | All events |\n\n#### Deal Events\n\n| Event | When it fires |\n|-------|---------------|\n| `deal.created` | The offer is accepted and the deal opens — whether it started with `POST /v2/offers` or in the PrivateAuto app. Fires once per deal, and always means a deal you can fetch now exists |\n| `deal.completed` | The deal closes: payment is acknowledged and the vehicle is marked sold |\n| `deal.cancelled` | Either party cancels the deal |\n| `deal.expired` | The deal expires without completing |\n| `deal.offer_accepted` | Both buyer and seller have confirmed the deal terms. Each side's confirmation time is on the deal as `buyer.confirmedDate` / `seller.confirmedDate` |\n| `deal.terms_confirmed` | New name for `deal.offer_accepted`, same payload. Delivered only to an endpoint that lists it; see **Deprecations** |\n| `deal.buyer_joined` | The buyer signs in and joins the deal |\n| `deal.seller_joined` | The seller signs in and joins the deal |\n| `deal.buyer_ready` | The buyer marks \"Ready to Close\" after completing every required step |\n| `deal.seller_ready` | The seller marks \"Ready to Close\" after completing every required step |\n| `deal.co_seller_invited` | The seller sends a co-seller an invitation. The co-seller is not on the deal response — use this event if you need to know a third signer is coming |\n| `deal.title_submitted` | Either party confirms the title information (ownership, registration, lien holder); photos may not be uploaded yet. Fires once per deal, on whichever side confirms first — in a dealer-acquisition deal that is usually the buyer |\n| `deal.title_approved` | The seller marks their uploaded title photos complete. Seller-driven, not a PrivateAuto review |\n| `deal.title_uploaded` | New name for `deal.title_approved`, same payload. Delivered only to an endpoint that lists it |\n| `deal.docs_submitted` | The parties have signed every required closing document, starting review |\n| `deal.docs_approved` | PrivateAuto approves the closing documents |\n| `deal.payment_initiated` | The buyer starts the payment transfer |\n| `deal.payment_acknowledged` | The seller acknowledges receiving the payment |\n| `deal.amount_changed` | The deal amount changes after the deal opened. Not sent when the deal is created |\n| `deal.negative_equity_identified` | PrivateAuto's payoff review finds the seller's loan payoff exceeds the deal amount |\n| `deal.negative_equity_reported` | The same finding, reached when the deal amount is changed in the app. Same payload as `deal.negative_equity_identified`; only one of the two fires for a deal, so **subscribe to both**, or to `deal.negative_equity_flagged` alone |\n| `deal.negative_equity_flagged` | Replaces both events above: fires once whichever path found it, with `source` set to `service` (payoff review) or `user` (amount changed in the app). Delivered only to an endpoint that lists it |\n| `deal.negative_equity_funded` | The negative-equity balance has been paid |\n| `deal.loan_payoff_docs` | The seller uploads loan payoff documents (the first upload only) |\n| `deal.loan_payoff_confirmed` | PrivateAuto confirms the loan payoff |\n| `deal.poa_approved` | **Deprecated — removal on or after 1 February 2027.** The Power of Attorney is fully signed. Replaced by `document.completed` with `docClassification: 'poa'` |\n| `deal.bill_of_sale_approved` | **Deprecated — removal on or after 1 February 2027.** The Bill of Sale is fully signed. Replaced by `document.completed` with `docClassification: 'bill-of-sale'` |\n\n**Deal event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | The deal id — use it with `GET /v2/deals/{dealId}` |\n| `guid` | string | The transaction's stable handle; the same as the offer's (see [Identifiers](#section/Identifiers)) |\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| `negativeEquity` | boolean \\| null | Whether the loan payoff exceeds the deal amount |\n| `callerReferenceId` | string \\| null | The `callerReferenceId` you sent on `POST /v2/offers` for the offer 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 | On `deal.title_submitted`, `deal.title_approved`, `deal.loan_payoff_docs`, `deal.poa_approved` and `deal.bill_of_sale_approved` only — see below |\n\n> Deal payloads do not carry a `vin`. Fetch `GET /v2/deals/{dealId}` for the deal's `listingId`, then\n> `GET /v2/vehicles/{vehicleId}` with that id for the VIN and the full vehicle.\n\nThe events listed under `documents` above carry short-lived signed links to the files:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `documents[].filename` | string | Original filename |\n| `documents[].signedUrl` | string | Pre-signed HTTPS URL — fetch it before it expires |\n| `documents[].expiresAt` | string | ISO 8601 time the link stops working: 4 hours after the event |\n\nDownload the file promptly. To get fresh links later, call `GET /v2/deals/{dealId}/documents`.\n\n`deal.loan_payoff_docs` and `deal.loan_payoff_confirmed` describe the seller's loan payoff rather than\nthe deal itself: their `id` is not the deal id. Use their `dealId`.\n\n`deal.poa_approved` and `deal.bill_of_sale_approved` describe a document, and carry the document\npayload below — `id` is the document, `dealId` the deal.\n\n#### Document Events\n\nThese are the **current** per-document signature events. Prefer them over the deprecated\ndeal-level `deal.poa_approved` / `deal.bill_of_sale_approved` events.\n\n| Event | When it fires |\n|-------|---------------|\n| `document.signature_added` | One signer signs a document. Fires once per signer — a document signed by seller, co-seller and buyer fires it three times |\n| `document.completed` | Every required signer on a document has signed. Fires once per document, whatever its type |\n| `deal.document_uploaded` | A partner uploads a document to a deal with `POST /v2/deals/{dealId}/documents` |\n\nTell document types apart by `docClassification` on the payload, **not** by event name.\n\n**Document event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | The document id |\n| `dealId` | string | The deal the document belongs to |\n| `status` | string | Document status |\n| `docClassification` | string | The document type, e.g. `bill-of-sale`, `poa` |\n| `signers` | array | `{ signerRole, signedAt }` for each signer — `seller`, `buyer` or `coSeller` |\n| `documents` | array | Signed links to the file, as above (on the deprecated deal-level events) |\n\n#### Offer Events\n\n| Event | When it fires |\n|-------|---------------|\n| `offer.created` | An offer is made — by `POST /v2/offers`, or by a buyer in the PrivateAuto app |\n| `offer.accepted` | The offer is accepted |\n| `offer.rejected` | The offer is declined. The offer's `status` reads `declined` |\n| `offer.declined` | New name for `offer.rejected`, same payload. Delivered only to an endpoint that lists it |\n| `offer.cancelled` | The offer is withdrawn by the side that made it. The offer's `status` reads `deleted` |\n| `offer.withdrawn` | New name for `offer.cancelled`, same payload. Delivered only to an endpoint that lists it |\n\n**Offer event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | The offer id — use it with `GET /v2/offers/{offerId}` |\n| `guid` | string | The transaction's stable handle; the deal opened from this offer carries the same one |\n| `status` | string | Current offer status |\n| `listingId` | string | The vehicle the offer is for — use it with `GET /v2/vehicles/{vehicleId}` |\n| `amount` | number | Offer amount in dollars |\n| `buyerId` | string | The user who made the offer — named for the usual case, where the buyer makes it |\n| `sellerId` | string | The user the offer was made to |\n| `callerReferenceId` | string \\| null | The `callerReferenceId` you sent on `POST /v2/offers`. 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 vehicle listing is created |\n| `listing.updated` | A listing is edited in a way no more specific event below describes. One change produces at most one listing event |\n| `listing.published` | A listing goes live on the marketplace |\n| `listing.sold` | A listing is marked sold, by hand or when its deal completes |\n| `listing.deleted` | A listing is deactivated, expires or is deleted |\n| `listing.ownership_set` | The vehicle's ownership type (owned, financed or leased) is set by PrivateAuto |\n| `listing.ownership_submitted` | The seller declares the ownership type while listing. Same payload as `listing.ownership_set`; which one fires depends on who set it, not the value, so **subscribe to both**, or to `listing.ownership_updated` alone |\n| `listing.ownership_updated` | Replaces both events above: fires once whoever set it, with `source` set to `service` (PrivateAuto) or `user` (the seller). Delivered only to an endpoint that lists it |\n\n**Listing event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | The vehicle id — use it with `GET /v2/vehicles/{vehicleId}` |\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` (when ownership is declared) |\n| `vehicleHaveLien` | boolean | Whether the vehicle has an active lien |\n\n#### Dealer Events\n\n| Event | When it fires |\n|-------|---------------|\n| `dealer.linked` | Your account gained standing to act for a dealership: the first request made with an OAuth credential that dealership approved (one event per location in that dealer group), or PrivateAuto linking it for you. Your own credentials get the same standing, until PrivateAuto revokes it |\n| `dealer.unlinked` | That standing was revoked. Offers you send afterwards are no longer started for that dealership |\n\nDelivered only to the partner the link belongs to — never to another partner linked to the same\ndealership. Your own organization is always linked and never produces these events. Further requests\nwith the same OAuth credential do not re-send `dealer.linked`, and for OAuth, `linkedAt` is when\nPrivateAuto first saw the credential used, not when the dealer approved it.\n\n**Dealer event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | The link's 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: `hmac`, `api-key`, `m2m` or `oauth` |\n| `clientId` | string \\| null | OAuth links: the OAuth application the dealer approved |\n| `actingUserId` | string \\| null | OAuth links: the user who approved it |\n| `onBehalfOfOrganization` | string \\| null | OAuth links: the dealer group that approved it. One approval covers the 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### Reading the full record\n\nPayloads are deliberately compact. Use the webhook as the **signal** and the v2 read as the **source of\ntruth**:\n\n| Event family | Payload id | Read the full record with |\n|---|---|---|\n| `deal.*` | `id` (the deal) | `GET /v2/deals/{dealId}` |\n| `offer.*` | `id` (the offer); `listingId` | `GET /v2/offers/{offerId}`; `GET /v2/vehicles/{vehicleId}` |\n| `listing.*` | `id` (the vehicle) | `GET /v2/vehicles/{vehicleId}` |\n| `document.*`, `deal.document_uploaded`, `deal.poa_approved`, `deal.bill_of_sale_approved` | `dealId`; `id` (the document) | `GET /v2/deals/{dealId}/documents`: every document on the deal, uploaded and PrivateAuto-generated, with fresh links. Find the row whose `id` matches the payload's `id` |\n| `deal.title_submitted`, `deal.title_approved` | `id` (the deal) | `GET /v2/deals/{dealId}/documents` |\n| `deal.loan_payoff_docs`, `deal.loan_payoff_confirmed` | `dealId` | `GET /v2/deals/{dealId}` and its documents |\n| `dealer.*` | `organizationId` | No v2 read returns dealer links yet, so the payload is the record. Keep `organizationId` as the dealership's PrivateAuto id |\n| Any delivery | `eventId` (header `X-PA-Event-Id`) | `GET /v2/webhooks/deliveries` to find it, then `GET /v2/webhooks/deliveries/{logId}` for the body we sent and each attempt |\n\nThat includes offers you send for a linked dealership: the reads return the offers and deals you\nstarted, their documents, and the vehicles you created or that belong to the dealership, although\nthey belong to the dealership's organization.\n\n### Event sequences by transaction type\n\nWhich events arrive, and in what order, depends on which side you are on and how the deal started.\n\n#### Who is on each side\n\nEach deal is classified by whether a dealership is on each side — `seller.organizationId` and\n`buyer.organizationId` on the deal:\n\n| Seller is a dealership | Buyer is a dealership | Type | Plain English |\n|---|---|---|---|\n| No | No | **C2C** | Consumer sells to consumer |\n| No | Yes | **C2D** | A dealer buys from a consumer |\n| Yes | No | **D2C** | A dealer sells to a consumer |\n| Yes | Yes | **D2D** | Wholesale between two dealers |\n\n#### 1. You are the buyer, and you sent the offer\n\nThe most common shape: you send `POST /v2/offers` naming the seller, and the seller accepts.\n\n```\nWhat happens                       Event delivered              Notes\n─────────────────────────────────  ───────────────────────────  ─────────────────────────────────\nPOST /v2/offers                    listing.created              when a listing is created for\n                                                                the vehicle\n                                   offer.created                dealId is still null\n─────────────────────────────────  ───────────────────────────  ─────────────────────────────────\nthe seller follows their link      offer.accepted\nand accepts                        deal.created                 dealId now exists\n─────────────────────────────────  ───────────────────────────  ─────────────────────────────────\neach signer signs a document       document.signature_added     one per signer\nthe last signer signs              document.completed           once per document\n                                   deal.bill_of_sale_approved   deprecated; Bill of Sale only\n─────────────────────────────────  ───────────────────────────  ─────────────────────────────────\nPrivateAuto approves the documents deal.docs_approved\n─────────────────────────────────  ───────────────────────────  ─────────────────────────────────\nyou send the funds                 deal.payment_initiated\n─────────────────────────────────  ───────────────────────────  ─────────────────────────────────\nthe seller confirms receipt        deal.payment_acknowledged\n                                   deal.completed\n```\n\n**Minimum subscription** for this flow: `deal.created`, `document.completed`,\n`deal.payment_initiated`, `deal.payment_acknowledged`, `deal.completed`. Add `offer.rejected`,\n`offer.cancelled`, `deal.cancelled` and `deal.expired` to see it end early, and `deal.docs_approved`\nto mirror PrivateAuto's \"all documents reviewed\" state.\n\n#### 2. You are the buyer, and the seller listed in the app\n\nThe seller lists the vehicle on PrivateAuto, a buyer from your organization makes an offer in the app,\nand the seller accepts:\n\n```\nlisting.created          the seller creates the listing (only if it was started through your integration)\nlisting.published        the seller publishes it\noffer.created            your buyer makes an offer\noffer.accepted           the seller accepts\ndeal.created             the deal opens\n{ then the same documents / payment / completion chain as 1 }\n```\n\n#### 3. You are the seller\n\nThe mirror image: you send `POST /v2/offers` naming the buyer, or a buyer makes an offer on a vehicle\nyou listed.\n\n```\nlisting.created              you create the listing\nlisting.published            it goes live\nlisting.ownership_set OR     the ownership type is set by PrivateAuto\n  listing.ownership_submitted  or by you while listing\n─────────────────────────────────────────────────────────────────────────\noffer.created                the buyer makes an offer (or you send one)\noffer.accepted               the offer is accepted (possibly after counters)\ndeal.created                 the deal opens\n{ documents round — you sign the Bill of Sale, Power of Attorney and so on as the seller }\ndeal.docs_approved\ndeal.payment_initiated       the buyer sends the funds\ndeal.payment_acknowledged    you confirm receipt\ndeal.completed\nlisting.sold                 the listing is marked sold once the deal completes\n```\n\n#### 4. D2D — dealer to dealer\n\nBoth sides are dealerships. You receive events for a deal when your organization is on either side,\nwith the same set as C2D or D2C. If both organizations are yours you see both a `listing.published`\n(seller side) and an `offer.created` (buyer side) for the same deal: dedupe on the deal's `guid`.\n\n#### 5. C2C — consumer to consumer\n\nYou receive events only for offers and deals started through your integration, since neither party\nbelongs to your organization. That needs your account's routing to include `appSource` (see Routing\nbelow).\n\n#### Document signing, signer by signer\n\nThe Bill of Sale and Power of Attorney — and any other document PrivateAuto has signed in the app —\neach produce one `document.signature_added` per signer and one `document.completed` when the last\nsigner is done:\n\n```\nseller signs          document.signature_added (signerRole: seller)\nbuyer signs           document.signature_added (signerRole: buyer)\n                      document.completed           (every signer done)\n                      deal.bill_of_sale_approved   (deprecated, Bill of Sale only)\n                      deal.poa_approved            (deprecated, Power of Attorney only)\n```\n\nEach `document.signature_added` payload carries:\n\n```json\n{\n  \"id\": \"<documentId>\",\n  \"dealId\": \"<dealId>\",\n  \"docClassification\": \"bill-of-sale\",\n  \"signers\": [{ \"signerRole\": \"seller\", \"signedAt\": \"<ISO date>\" }]\n}\n```\n\nBranch on `docClassification`, not on the event name. The deprecated `deal.bill_of_sale_approved` and\n`deal.poa_approved` keep firing until **1 February 2027**; see [Deprecations](#section/Webhooks).\n\nWhen a deal has a co-seller, the Bill of Sale and Power of Attorney each gain a signer:\n`document.signature_added` fires three times (seller, co-seller, buyer) and `document.completed` once.\n\n#### Negative equity\n\nWhen the seller's loan payoff is more than the deal amount, PrivateAuto flags the deal\n`negativeEquity: true` and sends one of two events:\n\n| Event | Reached when |\n|---|---|\n| `deal.negative_equity_reported` | The deal amount is changed in the app and drops below the payoff |\n| `deal.negative_equity_identified` | PrivateAuto's payoff review finds it |\n\nBoth carry `negativeEquity: true`; the event name is the only difference. `deal.negative_equity_funded`\nfollows once the shortfall is paid.\n\n#### Loan payoff documents\n\nFor a seller with an outstanding loan on the vehicle:\n\n```\nthe seller uploads a payoff document  →  deal.loan_payoff_docs       (first upload only)\nPrivateAuto confirms the payoff       →  deal.loan_payoff_confirmed\n```\n\n#### Documents on each type of deal\n\n| Document | C2C | C2D | D2C | D2D | Notes |\n|---|---|---|---|---|---|\n| **Title photos** (front / back) | ✅ | ✅ | ✅ | ✅ | Title information confirmed → `deal.title_submitted`; photos uploaded and marked complete → `deal.title_approved` |\n| **Bill of Sale** (`docClassification: 'bill-of-sale'`) | ✅ | ✅ | ✅ | ✅ | Always generated; both parties sign |\n| **Power of Attorney** (`docClassification: 'poa'`) | — | ✅ | ✅ | ✅ | Generated when a dealer is on either side |\n| **Loan payoff documents** | seller with a loan | seller with a loan | — | — | Only when the consumer seller has a loan on the vehicle. `deal.loan_payoff_docs`, `deal.loan_payoff_confirmed` |\n| **Self-inspection photos** | optional | optional | — | — | Requested by the buyer; not signed, and no event |\n| **State paperwork** (odometer, lien release, title application) | varies | varies | varies | varies | Generated by the deal's state as needed. No event of its own; tracked by `documentsStatus` |\n\n`GET /v2/deals/{dealId}/documents` returns all of these in one list, with fresh 4-hour links — you do\nnot need to know where each is kept. PrivateAuto does not generate a purchase agreement separate from\nthe Bill of Sale (which serves as one), a financing addendum, or dealer \"we-owe\" forms.\n\n#### Routing\n\nYour account's routing setting, `webhookScope`, decides which records' events reach you. PrivateAuto\nsets it; the default is `both`.\n\n| `webhookScope` | Listings | Offers and deals | Documents |\n|---|---|---|---|\n| `appSource` | Listings started through your integration | Offers and deals started through your integration | Those on a deal that matches |\n| `organization` | Listings owned by your organization — not ones you created for a linked dealership | Deals with your organization on either side — not ones you start for a linked dealership, which carry the dealership's organization | Those on a deal with your organization on either side |\n| `both` (default) | Either | Either | Either |\n\n`dealer.*` events reach you for your own links only, whatever the setting.\n\nIf you are not receiving an event you expect, check in this order: that routing covers the record,\nthat the endpoint's subscriptions include the event, and that the endpoint is `active`.\n\n#### Building for change\n\n1. **Process events by name, not by order.** Several can arrive together (`offer.accepted` and\n   `deal.created`, for example); treat their order as informational.\n2. **Dedupe on `eventId`.** A retried delivery carries the same one.\n3. **Read the full record from the v2 reads** when you need more than the payload carries.\n4. **Move off the deprecated document events before 1 February 2027.** Subscribe to `document.*` and\n   branch on `docClassification`. Until then you receive both, so moving early costs nothing.\n5. **Treat a missing event as possibly legitimate.** The catalog says what *can* fire, not what *must*:\n   some deals skip `offer.accepted`, and a deal can be marked sold without a separate listing event.\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#### Renamed and merged events\n\nSome event names in the Event Types catalog above have a canonical replacement. The\ndeprecated names are **not** being removed and have no removal date: they stay subscribable and keep\nfiring with the payload they have today. Wildcard subscriptions keep receiving the deprecated names\nfor now and move to the canonical names at a cut-over date we will announce here (see below).\n\n| Deprecated event | Canonical event | `source` on the canonical event |\n|---|---|---|\n| `deal.offer_accepted` | `deal.terms_confirmed` | — |\n| `deal.title_approved` | `deal.title_uploaded` | — |\n| `offer.cancelled` | `offer.withdrawn` | — |\n| `offer.rejected` | `offer.declined` | — |\n| `deal.negative_equity_identified` | `deal.negative_equity_flagged` | `service` |\n| `deal.negative_equity_reported` | `deal.negative_equity_flagged` | `user` |\n| `listing.ownership_set` | `listing.ownership_updated` | `service` |\n| `listing.ownership_submitted` | `listing.ownership_updated` | `user` |\n\nThe canonical event fires at exactly the moment its deprecated counterpart does and carries the same\npayload. Where two deprecated events merged into one canonical event, it adds a `source` field naming\nthe path that fired it: `user` for the user-side flow, `service` for the admin or service path.\n\n**When each canonical event fires** (the trigger is its deprecated counterpart's, unchanged):\n\n| Canonical event | When it fires |\n|---|---|\n| `deal.terms_confirmed` | Both buyer and seller have confirmed the deal terms: the write that sets the second of `buyer.confirmedDate` / `seller.confirmedDate`. Fires where `deal.offer_accepted` does |\n| `deal.title_uploaded` | The seller marks their uploaded title attachment complete (`titleAttachment.completedDate` set). Seller-driven, not an admin review. Fires where `deal.title_approved` does |\n| `deal.negative_equity_flagged` | The payoff amount exceeds the deal amount (`negativeEquity` set `true`). `source: \"user\"` when the consumer-facing flow crossed the payoff threshold (where `deal.negative_equity_reported` fires); `source: \"service\"` when the admin/service payoff path accepted the payoff (where `deal.negative_equity_identified` fires). The two paths are mutually exclusive per deal |\n| `listing.ownership_updated` | The listing's `ownershipInfo.ownershipType` is set or changed. `source: \"user\"` when the seller answered the ownership question on listing setup (where `listing.ownership_submitted` fires); `source: \"service\"` when an admin or internal tool wrote it, including on insert (where `listing.ownership_set` fires) |\n| `offer.withdrawn` | The buyer withdraws an offer. Fires where `offer.cancelled` does |\n| `offer.declined` | The seller declines an offer. Fires where `offer.rejected` does |\n\nThe **Event sequences** and **Negative equity** sections above use the deprecated names. Advice to\n**subscribe to both** `deal.negative_equity_identified` and `deal.negative_equity_reported` (or both\n`listing.ownership_set` and `listing.ownership_submitted`) applies only to an endpoint that receives the\ndeprecated names (see the next table). An endpoint that receives `deal.negative_equity_flagged` or\n`listing.ownership_updated` gets one event per occurrence and reads `source` to tell the two paths apart.\n\n**Which name an endpoint receives** depends on what it subscribes to. Each endpoint receives each\nevent **once**:\n\n| Endpoint subscribes to | Receives |\n|---|---|\n| The deprecated name only | The deprecated name, payload unchanged |\n| The canonical name | The canonical name |\n| A wildcard that covers it (`deal.*`, `offer.*`, `listing.*`, `*`), and not the canonical name | The deprecated name, payload unchanged, until the announced cut-over |\n| The canonical name, alone, beside the deprecated name or beside a wildcard | The canonical name, once |\n\nThe `X-PA-Event` header, the `eventKey` (and so the `eventId` derived from it) and the delivery log\n(`GET /v2/webhooks/deliveries`) all carry the name actually delivered, with two exceptions. Both are written\nonce per partner rather than per endpoint, so no endpoint's subscription chooses their name, and both\nrecord the **deprecated** name:\n\n- a `dlq` row written because the event itself could not be processed after repeated attempts;\n- a `skipped` row with the error `no webhook destinations resolved`, written when you had no usable\n  destination at all (for example, your only endpoint was disabled after repeated failures and no\n  onboarding endpoint is configured).\n\nIf you filter the delivery log by `event=<canonical name>`, also query the deprecated name to see\nthose rows.\n\n`GET /v2/webhooks/catalog` lists the deprecated names under `deprecated`, each with its replacement.\n\n**Wildcard subscribers: nothing changes yet.** An endpoint subscribed to `deal.*`, `offer.*`,\n`listing.*` or `*` keeps receiving the deprecated names. Wildcard subscriptions move to the canonical\nnames at a cut-over date we will announce here. To switch earlier, add the canonical names to the\nendpoint's subscriptions beside the wildcard: from then on it receives those events under the canonical\nname, once. To stay on the deprecated names after the cut-over, subscribe to them explicitly.\n\nThe endpoint configured during onboarding, rather than through `/v2/webhooks/endpoints`, is\nunaffected: it keeps receiving the deprecated names, whatever it subscribes to.\n\n### Availability by release\n\nThis reference is a **superset**: it documents the v2 contract, and any given\nenvironment serves some prefix of it. Everything it documents that your environment\nhas, it documents correctly — but an endpoint appearing here is not a promise that\nthe environment you are pointed at serves it yet.\n\nThat gap is real rather than theoretical. The documentation site is built once and\npromoted, so it can describe a build newer than the service in front of you. As of\nthis writing the webhook **management** endpoints (`/v2/webhooks/endpoints`,\n`/subscriptions`, `/catalog`) are present in some environments and absent in others,\nwhile the v2 read endpoints are more widely deployed.\n\n**Check what you are actually running**, rather than inferring it from this page:\n\n| Question | Ask |\n|---|---|\n| Does this environment serve v2 at all? | `GET /v2/me` — `404` means no |\n| Which webhook events may I subscribe to? | `GET /v2/webhooks/catalog` — `404` means management is not deployed here |\n| What is the live contract? | `GET /api/docs-json` — the spec this environment is actually serving |\n\nA missing v2 route returns `404`, and an existing one you are not authenticated for\nreturns `401`. That difference is the cheapest way to tell \"not deployed\" from \"not\nauthorised\", and it is worth using before opening a support ticket.\n\nWhere webhook management is not yet available, your v1 configuration still applies:\nevents continue to be delivered to the endpoint configured for your account, under\nthe same delivery format and signature scheme. Nothing is lost by an environment\nbeing behind — only self-service is.\n",
    "version": "2.0.0",
    "contact": {},
    "x-api-stability": "beta"
  },
  "tags": [
    {
      "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": "deals",
      "description": "Deals your organization is party to — read the deal, act on it, and track its documents"
    },
    {
      "name": "offers",
      "description": "Offers on a deal — read them, and counter, accept, decline or withdraw"
    },
    {
      "name": "vehicles",
      "description": "Vehicles your organization has listed. v1 calls this resource `listings`; v2 names it for the thing you are working with rather than for the record we store."
    },
    {
      "name": "documents",
      "description": "Documents attached to a deal — uploads, generated paperwork, and short-lived signed URLs to fetch them"
    },
    {
      "name": "webhooks",
      "description": "Self-service webhook delivery — register endpoints, choose the events each receives, rotate secrets, and inspect delivery attempts"
    },
    {
      "name": "dealers",
      "description": "Dealer organizations on your partner allowlist"
    },
    {
      "name": "deal-invites",
      "description": "DealNow deal initiation — invite a prospect into a PrivateAuto deal"
    },
    {
      "name": "me",
      "description": "Introspect the calling credential — who it is and which scopes it holds"
    },
    {
      "name": "reports",
      "description": "Dashboards PrivateAuto has shared with you, read with a credential or a report link"
    },
    {
      "name": "wallets",
      "description": "Your organization's wallets and their transactions, as last reported by each wallet's provider"
    }
  ],
  "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
          }
        }
      },
      "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
          }
        }
      },
      "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"
        ]
      },
      "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"
        ]
      },
      "LeadContactV2Dto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Full name of the person selling the car",
            "example": "Jane Smith"
          },
          "email": {
            "type": "string",
            "description": "Email address of the person selling the car",
            "example": "jane@example.com"
          },
          "phone": {
            "type": "string",
            "description": "Phone number of the person selling the car",
            "example": "555-867-5309"
          },
          "message": {
            "type": "string",
            "description": "The seller's message or your notes about the car",
            "example": "Looking to sell my 2019 Accord. One owner, clean title."
          }
        }
      },
      "LeadVehicleV2Dto": {
        "type": "object",
        "properties": {
          "vin": {
            "type": "string",
            "description": "17-character Vehicle Identification Number of the seller's car",
            "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
          }
        }
      },
      "SubmitLeadV2Dto": {
        "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": "The person selling the car",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeadContactV2Dto"
              }
            ]
          },
          "vehicle": {
            "description": "The car the seller wants to sell to the dealership",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeadVehicleV2Dto"
              }
            ]
          },
          "listingId": {
            "type": "string",
            "description": "Link to an existing PrivateAuto listing ID",
            "example": "663b2f3c5e9d0b002345bcde"
          }
        },
        "required": [
          "callerReferenceId",
          "organizationId"
        ]
      },
      "RateLimitExceededResponseV2Dto": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "description": "HTTP status code",
            "example": 429
          },
          "error": {
            "type": "string",
            "description": "Error code",
            "example": "rate_limit_exceeded"
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation",
            "example": "Rate limit exceeded: 60 requests per minute"
          },
          "retryAfterMs": {
            "type": "number",
            "description": "Milliseconds until the oldest request leaves the window and capacity returns",
            "example": 42000
          }
        },
        "required": [
          "statusCode",
          "error",
          "message",
          "retryAfterMs"
        ]
      },
      "LookupLeadResponseV2Dto": {
        "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"
            ]
          },
          "organizationId": {
            "type": "string",
            "description": "The dealer organization this lead was submitted to",
            "example": "663a1f4d6fae0c003456abcd"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Timestamp when the lead was created",
            "example": "2026-04-16T14:22:00.000Z"
          }
        },
        "required": [
          "leadId",
          "callerReferenceId",
          "status",
          "organizationId",
          "createdAt"
        ]
      },
      "PartnerIdentityV2": {
        "type": "object",
        "properties": {
          "partnerId": {
            "type": "string",
            "description": "Your partner identifier — the `p` claim your tokens carry",
            "example": "acme"
          },
          "name": {
            "type": "string",
            "description": "Display name for your integration",
            "example": "Acme Motors"
          },
          "organizationId": {
            "type": "string",
            "description": "The dealership this credential acts as, when one is linked. Null for partners with no linked organization.",
            "nullable": true
          },
          "scopes": {
            "type": "array",
            "description": "Everything this credential is permitted to do. Check it at startup so a missing scope fails loudly here rather than surfacing as a 403 in production.",
            "items": {
              "type": "string",
              "enum": [
                "deals:read",
                "deals:write",
                "vehicles:read",
                "vehicles:write",
                "vehicles:publish",
                "marketplace:search",
                "documents:read",
                "documents:write",
                "deal-invites:write",
                "offers:write",
                "leads:write",
                "webhooks:read",
                "webhooks:manage",
                "dealers:manage",
                "dealers:lookup",
                "reports:read",
                "wallet:read"
              ]
            }
          },
          "apiVersion": {
            "type": "string",
            "description": "Contract version serving this request",
            "example": "2.0.0"
          }
        },
        "required": [
          "partnerId",
          "name",
          "scopes",
          "apiVersion"
        ]
      },
      "PartnerDealResponseV2": {
        "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": "Deprecated: use `price`, which carries the same value. Still returned.",
            "nullable": true,
            "deprecated": 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
          },
          "callerReferenceId": {
            "type": "string",
            "description": "The `callerReferenceId` you sent on `POST /v2/deal-invites`. Null when you sent none, and always null on an offer or deal another partner started: a reference is shown only to the partner that set it.",
            "nullable": true,
            "example": "INV-20261103-0042"
          },
          "price": {
            "type": "number",
            "description": "The deal's current price, in US dollars, not cents (18500 means $18,500). The latest offer's price, or the PrivateAuto Pay amount when no offer carries one. Always the same value as `amount`.",
            "nullable": true,
            "example": 18500
          }
        },
        "required": [
          "id",
          "guid",
          "status",
          "buyer",
          "seller",
          "dealState",
          "callerReferenceId"
        ]
      },
      "PartnerPageMetaV2": {
        "type": "object",
        "properties": {
          "page": {
            "type": "number",
            "description": "Zero-based index of the page returned",
            "example": 0
          },
          "limit": {
            "type": "number",
            "description": "Maximum items per page",
            "example": 50
          },
          "total": {
            "type": "number",
            "description": "Total items matching the query across all pages",
            "example": 137
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether a further page exists after this one",
            "example": true
          }
        },
        "required": [
          "page",
          "limit",
          "total",
          "hasMore"
        ]
      },
      "PartnerOfferResponseV2": {
        "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
          },
          "callerReferenceId": {
            "type": "string",
            "description": "The `callerReferenceId` you sent on `POST /v2/deal-invites`. Null when you sent none, and always null on an offer or deal another partner started: a reference is shown only to the partner that set it.",
            "nullable": true,
            "example": "INV-20261103-0042"
          }
        },
        "required": [
          "id",
          "guid",
          "status",
          "callerReferenceId"
        ]
      },
      "PartnerVehicleListingV2": {
        "type": "object",
        "properties": {
          "listingNo": {
            "type": "string",
            "description": "Public listing number (e.g. used in URLs)",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "description": "URL slug for the listing on the marketplace's public site",
            "nullable": true
          },
          "title": {
            "type": "string",
            "description": "Listing title text",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "live",
              "sold",
              "deactivated",
              "expired"
            ],
            "nullable": true
          },
          "price": {
            "type": "number",
            "description": "Asking price in dollars",
            "nullable": true
          },
          "sellerId": {
            "type": "string",
            "description": "The user offering the vehicle for sale",
            "nullable": true
          },
          "organizationId": {
            "type": "string",
            "description": "The organization the listing belongs to",
            "nullable": true
          },
          "appSource": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "status"
        ]
      },
      "PartnerVehicleDealV2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Deal id",
            "example": "663c3f4d6fae0c003456cdef"
          },
          "guid": {
            "type": "string",
            "description": "Cross-system handle for the deal, matching the `guid` on related webhook payloads. Null only when the deal itself has none.",
            "nullable": true
          }
        },
        "required": [
          "id"
        ]
      },
      "PartnerVehicleResponseV2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Vehicle id",
            "example": "6a024361a30d4d0026d00db2"
          },
          "vin": {
            "type": "string",
            "description": "17-character VIN (sourced from listing.vinNumber, uppercase-normalized at write time)",
            "nullable": true,
            "example": "WBA3B9C59FJ466190"
          },
          "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
          },
          "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
          },
          "condition": {
            "type": "string",
            "description": "Overall state of the vehicle, as characterised by the seller.",
            "enum": [
              "new",
              "used"
            ],
            "nullable": true
          },
          "ownershipInfo": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerOwnershipInfoV1"
              }
            ]
          },
          "listing": {
            "nullable": true,
            "description": "The current sale listing for this vehicle, or null when it is not listed. Always present today — a vehicle reaches the API only by being listed — but branch on it: vehicles will exist without a listing in future, and this field is where that will show up.",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerVehicleListingV2"
              }
            ]
          },
          "deals": {
            "nullable": true,
            "description": "Completed sales of this vehicle, newest first — or, for a vehicle your organization bought, the single deal that bought it. **Only populated when `expand=deals` is requested**; null otherwise, which is not the same as an empty array (that means expanded and none found).",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerVehicleDealV2"
            }
          },
          "dealNowId": {
            "type": "string",
            "nullable": true,
            "description": "Handle of the most recent DealNow offer on this vehicle. Only populated when `expand=deals`."
          }
        },
        "required": [
          "id"
        ]
      },
      "VehicleSpecV2Dto": {
        "type": "object",
        "properties": {
          "year": {
            "type": "number",
            "description": "Model year",
            "example": 2015,
            "minimum": 1900,
            "maximum": 2100
          },
          "make": {
            "type": "string",
            "description": "Manufacturer",
            "example": "BMW"
          },
          "model": {
            "type": "string",
            "description": "Model name",
            "example": "330i"
          },
          "trim": {
            "type": "string",
            "description": "Trim level",
            "example": "Sport"
          },
          "vin": {
            "type": "string",
            "description": "Vehicle identification number",
            "example": "WBA3B9C59FJ466190"
          },
          "mileage": {
            "type": "number",
            "description": "Odometer reading",
            "example": 62000
          },
          "bodyStyle": {
            "type": "string",
            "description": "Body style — sedan, SUV, coupe, etc.",
            "example": "sedan"
          },
          "exteriorColor": {
            "type": "string",
            "description": "Exterior color",
            "example": "Alpine White"
          },
          "interiorColor": {
            "type": "string",
            "description": "Interior color",
            "example": "Black"
          },
          "transmission": {
            "type": "string",
            "description": "Transmission type",
            "example": "automatic"
          },
          "driveType": {
            "type": "string",
            "description": "Drive type",
            "example": "RWD"
          },
          "fuel": {
            "type": "string",
            "description": "Fuel type",
            "example": "gasoline"
          },
          "cylinders": {
            "type": "string",
            "description": "Cylinder count",
            "example": "4"
          },
          "vehicleType": {
            "type": "string",
            "description": "Vehicle category",
            "enum": [
              "Auto",
              "ATV/OHV",
              "Motorcycle",
              "RV",
              "Boat"
            ],
            "default": "Auto"
          },
          "condition": {
            "type": "string",
            "description": "Overall condition",
            "enum": [
              "new",
              "used"
            ]
          }
        },
        "required": [
          "year",
          "make",
          "model"
        ]
      },
      "ListVehicleV2Dto": {
        "type": "object",
        "properties": {
          "vehicle": {
            "description": "The vehicle being listed",
            "allOf": [
              {
                "$ref": "#/components/schemas/VehicleSpecV2Dto"
              }
            ]
          },
          "price": {
            "type": "number",
            "description": "Asking price in dollars",
            "example": 18000,
            "minimum": 0
          },
          "title": {
            "type": "string",
            "description": "Listing title. Defaults to \"{year} {make} {model}\" when omitted.",
            "example": "2015 BMW 330i Sport — one owner"
          },
          "zip": {
            "type": "string",
            "description": "US ZIP code where the vehicle is located. Geocoded on write; an unresolvable ZIP is rejected. Omit it and the listing has no location, which excludes it from distance-filtered marketplace searches.",
            "example": "84043"
          }
        },
        "required": [
          "vehicle",
          "price"
        ]
      },
      "UpdateVehicleListingV2Dto": {
        "type": "object",
        "properties": {
          "price": {
            "type": "number",
            "description": "New asking price in dollars",
            "example": 17500,
            "minimum": 0
          }
        },
        "required": [
          "price"
        ]
      },
      "PartnerVehiclePhotoV2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Photo id, stable for the life of the photo",
            "example": "9f2c1e7a4b6d8e0f1a2b3c4d"
          },
          "url": {
            "type": "string",
            "description": "Absolute URL of the full-size image",
            "example": "https://app.example.com/static/listings/6a024361a30d4d0026d00db2/photos/partner-9f2c….jpg"
          },
          "position": {
            "type": "number",
            "description": "Zero-based display position. Position 0 is the cover photo.",
            "example": 0
          },
          "primary": {
            "type": "boolean",
            "description": "True for the cover photo shown on search results and as the first image"
          }
        },
        "required": [
          "id",
          "url",
          "position",
          "primary"
        ]
      },
      "PartnerVehiclePhotosResponseV2": {
        "type": "object",
        "properties": {
          "vehicleId": {
            "type": "string",
            "description": "Vehicle id",
            "example": "6a024361a30d4d0026d00db2"
          },
          "photos": {
            "description": "Photos in display order",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerVehiclePhotoV2"
            }
          }
        },
        "required": [
          "vehicleId",
          "photos"
        ]
      },
      "AddVehiclePhotoV2Dto": {
        "type": "object",
        "properties": {
          "file": {
            "type": "string",
            "format": "binary",
            "description": "JPEG, PNG or WebP image"
          }
        },
        "required": [
          "file"
        ]
      },
      "ReorderVehiclePhotosV2Dto": {
        "type": "object",
        "properties": {
          "photoIds": {
            "description": "Every photo id currently on the vehicle, each exactly once, in the new display order. The first becomes the cover photo. A list that omits or adds a photo is rejected rather than partially applied.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "photoIds"
        ]
      },
      "PartnerWebhookDeliveryResponseV2": {
        "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
          },
          "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
          },
          "payload": {
            "type": "object",
            "description": "The exact payload that was sent to the partner endpoint",
            "additionalProperties": true,
            "nullable": true
          },
          "status": {
            "type": "string",
            "description": "Delivery outcome. `failed` is one attempt your endpoint did not accept; it is retried after 1, 5 and 15 minutes, and every attempt is its own row sharing `payload.eventId`. `skipped` means the event never qualified for you, or that a pending retry was dropped because the endpoint was disabled (by you or by auto-disable), deleted or unsubscribed before it ran — after an auto-disable, reconcile those rows like `dlq`. `dry-run` is a shadow-mode record, logged without contacting you. `dlq` means delivery failed repeatedly and was abandoned, so it never arrived and will not be retried automatically.",
            "enum": [
              "delivered",
              "failed",
              "pending",
              "retrying",
              "skipped",
              "dry-run",
              "dlq",
              null
            ],
            "nullable": true
          },
          "error": {
            "type": "string",
            "description": "Error detail for a failed delivery. On a `dlq` row this is a fixed sentence rather than the underlying cause, which is internal to us.",
            "nullable": true
          }
        },
        "required": [
          "id"
        ]
      },
      "DealInviteCounterpartyV2Dto": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "The other party's email address. Their deal link is bound to it.",
            "example": "jane@example.com"
          },
          "name": {
            "type": "string",
            "description": "The other party's full name",
            "example": "Jane Smith"
          },
          "sendLink": {
            "type": "boolean",
            "description": "If true, PrivateAuto emails the other party their deal link. Same as the `buyerSendLink` / `sellerSendLink` on their side."
          }
        },
        "required": [
          "email"
        ]
      },
      "CreateDealInviteV2Dto": {
        "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. Without `partnerSide`, this names the OTHER party unless it belongs to a user of your organization or a linked dealership (when you name a dealer, only a user of that dealership), in which case you are the buyer and the deal is for that dealership. With `partnerSide: \"buyer\"` it names your own user. To name the other party, prefer `partnerSide` with `counterparty`.",
            "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. Without `partnerSide`, this names the OTHER party unless it belongs to a user of your organization or a linked dealership (when you name a dealer, only a user of that dealership), in which case you are the seller and the deal is for that dealership. With `partnerSide: \"seller\"` it names your own user. To name the other party, prefer `partnerSide` with `counterparty`.",
            "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": "Deprecated: use `price`, which means the same thing. Offered price, in US dollars, not cents (18500 means $18,500).",
            "example": 18500,
            "deprecated": true
          },
          "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)"
          },
          "callerReferenceId": {
            "type": "string",
            "description": "Your own reference for this invitation: printable ASCII with no spaces, up to 128 characters, unique within your account. Sending a reference again with the same VIN, buyer email and seller email returns the original invitation and changes nothing; sending it with a different VIN or emails is rejected with 409 `duplicate_reference`. The reference is returned on the offer and the deal and on their webhooks, and the offers and deals lists can be filtered by it.",
            "example": "INV-20261103-0042"
          },
          "partnerSide": {
            "type": "string",
            "description": "Which side of the deal you are on. When sent, it decides the side outright; without it the side is inferred from which of `buyerEmail` / `sellerEmail` is filled, as before. With `partnerSide`, the email on your own side (`sellerEmail` when you are the seller) may still name your own user, and must belong to your organization or the dealership the deal is for.",
            "enum": [
              "buyer",
              "seller"
            ],
            "example": "seller"
          },
          "counterparty": {
            "description": "The other party, the one being invited. Requires `partnerSide`. If you also send the old field for the counterparty's side (`buyerEmail`, `buyerName`, `buyerSendLink` when you are the seller), each must match or the request is rejected with 400 `counterparty_conflict`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/DealInviteCounterpartyV2Dto"
              }
            ]
          },
          "dealerOrganizationId": {
            "type": "string",
            "description": "The PrivateAuto organization id of the dealership this deal is for. When sent (or `dealerExternalId`), it decides the dealership; emails are no longer matched to other dealerships. Without `partnerSide`, the emails still decide which side you are on, matched only against users of the named dealership. It must be your own organization or a dealership linked to your partner account (see \"Acting for a linked dealership\"); otherwise 403 `dealer_not_authorized`.",
            "example": "663a1f2b4e8c9a001234abcd"
          },
          "dealerExternalId": {
            "type": "string",
            "description": "Your own identifier for the dealership: the `externalIds[].value` you see on `GET /v2/dealers`, in your account's namespace (not a WorkOS or PrivateAuto id). Resolved to the organization, then held to the same rule as `dealerOrganizationId`: an unknown identifier, or a dealership you may not act for, is 403 `dealer_not_authorized`. Sent with `dealerOrganizationId`, both must name the same dealership or the request is rejected with 400 `dealer_attribution_conflict`.",
            "example": "DLR-4471"
          },
          "price": {
            "type": "number",
            "description": "Offered price, in US dollars, not cents (18500 means $18,500). Stored as sent, without rounding. Optional: omitted or 0 means the price is not set yet, so a new invitation is created with a price of 0 and an open one you reuse keeps its price. Replaces `amount`; sending both with different values is rejected with 400 `price_conflict`.",
            "example": 18500
          }
        },
        "required": [
          "vin"
        ]
      },
      "DealInviteResponseV2": {
        "type": "object",
        "properties": {
          "offerId": {
            "type": "string",
            "description": "The price proposal this call created. Always present.",
            "example": "64a1f2e3b5c8d90012345678"
          },
          "dealId": {
            "type": "string",
            "description": "The deal, once one exists. **Null before the invitation is accepted** — under the offer-first model no deal exists yet, and v1 returned the offer id here under a `dealId` name, which 404s if you fetch it. Branch on null rather than assuming an id.",
            "nullable": true,
            "example": "64a1f2e3b5c8d90012345679"
          },
          "guid": {
            "type": "string",
            "description": "Stable opaque handle — unchanged from v1, and present on every related webhook payload.",
            "example": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8"
          },
          "callerReferenceId": {
            "type": "string",
            "description": "The `callerReferenceId` you sent, or null when you sent none.",
            "nullable": true,
            "example": "INV-20261103-0042"
          },
          "buyerLink": {
            "type": "string",
            "description": "Deep link for the buyer"
          },
          "sellerLink": {
            "type": "string",
            "description": "Deep link for the seller"
          }
        },
        "required": [
          "offerId",
          "guid",
          "callerReferenceId",
          "buyerLink",
          "sellerLink"
        ]
      },
      "DuplicateReferenceResponseV2": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error code",
            "example": "duplicate_reference"
          },
          "message": {
            "type": "string",
            "description": "Human-readable reason. Branch on `error`, not on this text.",
            "example": "callerReferenceId is already used for an invitation with a different VIN, buyer email or seller email"
          },
          "offerId": {
            "type": "string",
            "description": "The offer this `callerReferenceId` already names",
            "example": "64a1f2e3b5c8d90012345678"
          },
          "redirectUrl": {
            "type": "string",
            "description": "The generic error page (`/error`) in the user's PrivateAuto or DealNow app, matching your link platform. Public, with no token or account data in it, so it is safe to send the user to; it tells them something went wrong and links to their dashboard and support.",
            "example": "https://app.privateauto.com/error"
          }
        },
        "required": [
          "error",
          "message",
          "offerId",
          "redirectUrl"
        ]
      },
      "CounterOfferV2Dto": {
        "type": "object",
        "properties": {
          "price": {
            "type": "number",
            "description": "Your counter price, in US dollars, not cents (18500 means $18,500). Stored as sent, without rounding.",
            "example": 24500
          }
        },
        "required": [
          "price"
        ]
      },
      "ConfirmTitleV2ResponseDto": {
        "type": "object",
        "properties": {
          "dealId": {
            "type": "string",
            "description": "The deal that was updated."
          },
          "party": {
            "type": "string",
            "enum": [
              "buyer",
              "seller"
            ],
            "description": "The side the confirmation was recorded against."
          },
          "message": {
            "type": "string",
            "example": "Successfully confirmed title."
          }
        },
        "required": [
          "dealId",
          "party",
          "message"
        ]
      },
      "PartyServicePreferencesDto": {
        "type": "object",
        "properties": {
          "titlePurchaseShow": {
            "type": "boolean",
            "description": "Whether title-purchase options are shown to this party."
          }
        }
      },
      "UpdateServicePreferencesV2Dto": {
        "type": "object",
        "properties": {
          "buyer": {
            "$ref": "#/components/schemas/PartyServicePreferencesDto"
          },
          "seller": {
            "$ref": "#/components/schemas/PartyServicePreferencesDto"
          }
        }
      },
      "UpdateServicesV2ResponseDto": {
        "type": "object",
        "properties": {
          "dealId": {
            "type": "string"
          },
          "success": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "dealId",
          "success"
        ]
      },
      "CancelDealV2ResponseDto": {
        "type": "object",
        "properties": {
          "dealId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "example": "cancelled"
          },
          "offerId": {
            "type": "string",
            "nullable": true,
            "description": "The working offer at cancellation time, if there was one."
          }
        },
        "required": [
          "dealId",
          "status"
        ]
      },
      "CreateWebhookEndpointV2Dto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "HTTPS destination. Must resolve to a public address."
          },
          "description": {
            "type": "string",
            "description": "Your own label for this endpoint. Never used for routing."
          },
          "subscriptions": {
            "description": "Events to deliver here. Wildcards (`deal.*`, `*`) are accepted. An empty list means the endpoint receives nothing — it is inert, not a wildcard.",
            "maxItems": 100,
            "items": {
              "type": "string",
              "maxLength": 100
            },
            "type": "array"
          }
        },
        "required": [
          "url"
        ]
      },
      "UpdateWebhookEndpointV2Dto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Changing this returns the endpoint to `unverified`."
          },
          "description": {
            "type": "string"
          }
        }
      },
      "VerifyWebhookEndpointV2ResponseDto": {
        "type": "object",
        "properties": {
          "verified": {
            "type": "boolean",
            "description": "Whether the endpoint proved control of the destination."
          },
          "status": {
            "type": "number",
            "nullable": true,
            "description": "HTTP status your endpoint returned, if it responded."
          },
          "reason": {
            "type": "string",
            "description": "Why verification did not succeed. Returned verbatim so you can debug your listener."
          }
        },
        "required": [
          "verified"
        ]
      },
      "RotateWebhookSecretV2ResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "secret": {
            "type": "string",
            "description": "The new signing secret. Returned ONCE — no read path exposes it."
          },
          "previousSecretExpiresAt": {
            "format": "date-time",
            "type": "string",
            "nullable": true,
            "description": "Accept both the old and the new secret until this time — 15 minutes after rotation. Deliveries move to the new secret from the moment of the call, and within 5 minutes at the latest; none is signed with the old one after this time."
          }
        },
        "required": [
          "id",
          "secret"
        ]
      },
      "TestWebhookEndpointV2ResponseDto": {
        "type": "object",
        "properties": {
          "delivered": {
            "type": "boolean"
          },
          "status": {
            "type": "number",
            "nullable": true
          },
          "signed": {
            "type": "boolean",
            "description": "Whether the delivery carried a signature."
          },
          "error": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "delivered",
          "signed"
        ]
      },
      "WebhookCatalogNamespaceV2Dto": {
        "type": "object",
        "properties": {
          "namespace": {
            "type": "string"
          },
          "requiredScope": {
            "type": "string",
            "description": "The scope this namespace would require."
          }
        },
        "required": [
          "namespace",
          "requiredScope"
        ]
      },
      "WebhookCatalogDeprecatedEventV2Dto": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "description": "Deprecated event name. Still subscribable and still delivered under this name."
          },
          "replacement": {
            "type": "string",
            "description": "The canonical event that replaces it."
          }
        },
        "required": [
          "event",
          "replacement"
        ]
      },
      "WebhookCatalogV2Dto": {
        "type": "object",
        "properties": {
          "events": {
            "description": "Events this credential may subscribe to. Includes deprecated names, which stay subscribable — see `deprecated`.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "wildcards": {
            "description": "Namespace wildcards available to this credential.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "totalWildcardAvailable": {
            "type": "boolean",
            "description": "Whether a bare `*` is available. It requires entitlement to every namespace, and means new event types begin arriving without you changing anything — prefer explicit lists."
          },
          "notEntitled": {
            "description": "What you are not entitled to, and why.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookCatalogNamespaceV2Dto"
            }
          },
          "deprecated": {
            "description": "Deprecated event names in `events`, each with its canonical replacement. An endpoint subscribed to a deprecated name, or only to a wildcard that covers it (`deal.*`, `*`), receives it under the deprecated name with an unchanged payload; wildcard subscriptions move to the replacements at a cut-over date that will be announced. An endpoint that lists the replacement receives the replacement instead — once, even if it also lists the deprecated name or a wildcard. Where two deprecated events share one replacement, the replacement carries a `source` field: `user` for the user-path event, `service` for the admin/service-path one.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookCatalogDeprecatedEventV2Dto"
            }
          }
        },
        "required": [
          "events",
          "wildcards",
          "totalWildcardAvailable",
          "notEntitled",
          "deprecated"
        ]
      },
      "SubscriptionsV2Dto": {
        "type": "object",
        "properties": {
          "events": {
            "description": "Event names or wildcard patterns. `*` requires entitlement to every namespace, and means new event types start arriving without you changing anything — prefer explicit lists. Deprecated names are accepted; `GET /v2/webhooks/catalog` lists them under `deprecated` with their replacements.",
            "maxItems": 100,
            "items": {
              "type": "string",
              "maxLength": 100
            },
            "type": "array"
          }
        },
        "required": [
          "events"
        ]
      },
      "WebhookEndpointV2Dto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": [
              "unverified",
              "active",
              "disabled_by_partner",
              "disabled_by_failure"
            ],
            "description": "All four stop or permit delivery, and a partner debugging silence needs to know which. `disabled_by_failure` is set by us after sustained delivery failure and is surfaced here precisely because we cannot use a webhook to report that webhooks are broken."
          },
          "subscriptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "verifiedAt": {
            "format": "date-time",
            "type": "string",
            "nullable": true
          },
          "consecutiveFailures": {
            "type": "number"
          },
          "disabledAt": {
            "format": "date-time",
            "type": "string",
            "nullable": true
          },
          "disabledReason": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "nullable": true
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "url",
          "description",
          "state",
          "subscriptions",
          "verifiedAt",
          "consecutiveFailures",
          "disabledAt",
          "disabledReason",
          "createdAt",
          "updatedAt"
        ]
      },
      "DealerExternalIdV2": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "Your identifier for this dealership",
            "example": "D-1042"
          },
          "label": {
            "type": "string",
            "description": "Optional human note, e.g. a rooftop name",
            "nullable": true
          },
          "linkedAt": {
            "type": "string",
            "description": "When the link was established",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "value"
        ]
      },
      "DealerV2": {
        "type": "object",
        "properties": {
          "organizationId": {
            "type": "string",
            "description": "PrivateAuto dealership id — use it wherever an organization is expected"
          },
          "name": {
            "type": "string",
            "description": "Dealership name",
            "nullable": true
          },
          "externalIds": {
            "description": "Your identifiers for this dealership. Only ids in your own namespace are returned — a dealership linked to several integrations never exposes another system’s ids to you. More than one is normal where a dealership has multiple rooftops.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DealerExternalIdV2"
            }
          }
        },
        "required": [
          "organizationId",
          "externalIds"
        ]
      },
      "MarketplaceListingV2": {
        "type": "object",
        "properties": {
          "listingNo": {
            "type": "string",
            "description": "Public listing number",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "description": "URL slug on the marketplace’s public site",
            "nullable": true
          },
          "title": {
            "type": "string",
            "description": "Listing title text",
            "nullable": true
          },
          "price": {
            "type": "number",
            "description": "Asking price in dollars",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "MarketplaceVehicleV2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Vehicle id",
            "example": "6a024361a30d4d0026d00db2"
          },
          "vin": {
            "type": "string",
            "description": "17-character VIN",
            "nullable": true
          },
          "year": {
            "type": "number",
            "description": "Model year",
            "nullable": true
          },
          "make": {
            "type": "string",
            "description": "Manufacturer",
            "nullable": true
          },
          "model": {
            "type": "string",
            "description": "Model name",
            "nullable": true
          },
          "trim": {
            "type": "string",
            "description": "Trim level",
            "nullable": true
          },
          "bodyStyle": {
            "type": "string",
            "description": "Body style",
            "nullable": true
          },
          "mileage": {
            "type": "number",
            "description": "Odometer reading",
            "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",
            "nullable": true
          },
          "fuel": {
            "type": "string",
            "description": "Fuel type",
            "nullable": true
          },
          "cylinders": {
            "type": "string",
            "description": "Cylinder count",
            "nullable": true
          },
          "location": {
            "type": "string",
            "description": "City and state the vehicle is located in. Never a street address.",
            "nullable": true,
            "example": "Lehi, UT"
          },
          "marketplaces": {
            "type": "array",
            "description": "Which marketplaces this vehicle is listed on — a vehicle can be on more than one, and more marketplaces are planned, so read this rather than assuming everything came from the one you searched.\n\nListings created before marketplaces were recorded carry no value of their own; for those this reports the marketplace you searched, since they are published everywhere.",
            "items": {
              "type": "string",
              "enum": [
                "privateauto",
                "dealnow"
              ]
            }
          },
          "listing": {
            "description": "The public sale listing",
            "allOf": [
              {
                "$ref": "#/components/schemas/MarketplaceListingV2"
              }
            ]
          }
        },
        "required": [
          "id",
          "listing"
        ]
      },
      "ReportSummaryV2": {
        "type": "object",
        "properties": {
          "shareId": {
            "type": "string",
            "description": "The share id. Use it to read the report."
          },
          "name": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "snapshot"
            ],
            "description": "`live` shows the dashboard as it is now; `snapshot` shows a version frozen when it was published."
          },
          "expiresAt": {
            "format": "date-time",
            "type": "string",
            "description": "After this the report can no longer be read."
          }
        },
        "required": [
          "shareId",
          "name",
          "mode",
          "expiresAt"
        ]
      },
      "ReportListV2": {
        "type": "object",
        "properties": {
          "reports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReportSummaryV2"
            }
          }
        },
        "required": [
          "reports"
        ]
      },
      "ReportLayoutItemV2": {
        "type": "object",
        "properties": {
          "i": {
            "type": "string",
            "description": "The id of the widget this cell positions."
          },
          "x": {
            "type": "number"
          },
          "y": {
            "type": "number"
          },
          "w": {
            "type": "number"
          },
          "h": {
            "type": "number"
          }
        },
        "required": [
          "i",
          "x",
          "y",
          "w",
          "h"
        ]
      },
      "ReportDateRangeV2": {
        "type": "object",
        "properties": {
          "preset": {
            "type": "string",
            "enum": [
              "7d",
              "30d",
              "90d",
              "12m"
            ],
            "description": "A rolling window ending today."
          },
          "from": {
            "type": "string",
            "description": "Start of a fixed window, `YYYY-MM-DD`."
          },
          "to": {
            "type": "string",
            "description": "End of a fixed window, `YYYY-MM-DD`."
          }
        }
      },
      "ReportWidgetV2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "catalogKey": {
            "type": "string",
            "description": "The widget catalog entry this widget shows."
          },
          "title": {
            "type": "string"
          },
          "viz": {
            "type": "string",
            "enum": [
              "kpi",
              "line",
              "area",
              "bar",
              "stacked-bar",
              "donut",
              "table"
            ]
          },
          "dateRangeOverride": {
            "description": "Replaces the report's date range for this widget.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ReportDateRangeV2"
              }
            ]
          },
          "refreshSeconds": {
            "type": "number",
            "description": "How often a viewer should refresh this widget, in seconds."
          }
        },
        "required": [
          "id",
          "catalogKey",
          "viz"
        ]
      },
      "ReportFiltersV2": {
        "type": "object",
        "properties": {
          "dateRange": {
            "description": "The date range widgets use unless they override it.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ReportDateRangeV2"
              }
            ]
          }
        }
      },
      "ReportV2": {
        "type": "object",
        "properties": {
          "shareId": {
            "type": "string",
            "description": "The share id. Use it to read the report."
          },
          "name": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "snapshot"
            ],
            "description": "`live` shows the dashboard as it is now; `snapshot` shows a version frozen when it was published."
          },
          "expiresAt": {
            "format": "date-time",
            "type": "string",
            "description": "After this the report can no longer be read."
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "number",
            "description": "Snapshot only: the published version shown."
          },
          "publishedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Snapshot only: when that version was published."
          },
          "layout": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReportLayoutItemV2"
            }
          },
          "widgets": {
            "description": "Widgets this partner may see today. A widget whose data falls outside what the partner may see is left out, with its layout cell.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReportWidgetV2"
            }
          },
          "filters": {
            "$ref": "#/components/schemas/ReportFiltersV2"
          }
        },
        "required": [
          "shareId",
          "name",
          "mode",
          "expiresAt",
          "layout",
          "widgets",
          "filters"
        ]
      },
      "WalletOrganizationV2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "PrivateAuto organization id"
          },
          "name": {
            "type": "string",
            "description": "Organization name",
            "nullable": true
          },
          "isLocation": {
            "type": "boolean",
            "description": "Whether this organization is a location of yours rather than your organization itself. A parent organization's credential lists its locations' wallets too; a location's credential lists only its own."
          }
        },
        "required": [
          "id",
          "name",
          "isLocation"
        ]
      },
      "WalletBalanceV2": {
        "type": "object",
        "properties": {
          "available": {
            "type": "integer",
            "description": "Balance last reported by the wallet provider, in cents. Negative when the provider reports a negative balance.",
            "example": 1250000
          },
          "pendingIn": {
            "type": "integer",
            "description": "Total of pending transfers into this wallet, in cents. Not yet included in `available`.",
            "example": 0
          },
          "pendingOut": {
            "type": "integer",
            "description": "Total of pending transfers out of this wallet, in cents",
            "example": 250000
          }
        },
        "required": [
          "available",
          "pendingIn",
          "pendingOut"
        ]
      },
      "PartnerWalletResponseV2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Wallet id"
          },
          "organization": {
            "description": "The organization this wallet belongs to",
            "allOf": [
              {
                "$ref": "#/components/schemas/WalletOrganizationV2"
              }
            ]
          },
          "provider": {
            "type": "string",
            "description": "The payments provider that holds this wallet: currently `checkbook` or `dwolla`. More providers may be added without a new API version, so treat an unrecognised value as valid. An organization can hold wallets at more than one provider.",
            "example": "checkbook"
          },
          "status": {
            "type": "string",
            "description": "Wallet status at the provider",
            "enum": [
              "verified",
              "unverified",
              "suspended",
              "closed"
            ]
          },
          "isPrimary": {
            "type": "boolean",
            "description": "Whether this is the organization's primary wallet"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code",
            "example": "USD"
          },
          "balance": {
            "$ref": "#/components/schemas/WalletBalanceV2"
          },
          "balanceAsOf": {
            "type": "string",
            "description": "When PrivateAuto last received `balance.available` from the provider, even if the figure did not change. `null` when it has not been refreshed since we began recording this.",
            "format": "date-time",
            "nullable": true
          },
          "balanceProviderAsOf": {
            "type": "string",
            "description": "The provider's own time for `balance.available`, where the provider reports one; otherwise `null`.",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "organization",
          "provider",
          "status",
          "isPrimary",
          "currency",
          "balance",
          "balanceAsOf",
          "balanceProviderAsOf"
        ]
      },
      "WalletCounterpartyV2": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "What is on the other side: `wallet`, `bank`, `individual`, `organization` or `operating_account`. More values may be added; treat an unrecognised one as valid.",
            "example": "bank"
          }
        },
        "required": [
          "type"
        ]
      },
      "PartnerWalletTransactionResponseV2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Transaction id"
          },
          "walletId": {
            "type": "string",
            "description": "The wallet this transaction was listed under"
          },
          "type": {
            "type": "string",
            "description": "Kind of transaction: `deposit`, `withdrawal`, `transfer` or `loan-payoff`. More values may be added; treat an unrecognised one as valid.",
            "example": "transfer"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed",
              "cancelled"
            ]
          },
          "direction": {
            "type": "string",
            "description": "`in` when money moves into this wallet, `out` when it moves out",
            "enum": [
              "in",
              "out"
            ]
          },
          "amount": {
            "type": "integer",
            "description": "Amount in cents, always positive; see `direction`",
            "example": 250000
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code",
            "example": "USD"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "eta": {
            "type": "string",
            "description": "Expected completion time, where the provider gives one",
            "format": "date-time",
            "nullable": true
          },
          "network": {
            "type": "string",
            "description": "Payment network, e.g. `ach`, `rtp`, `mail` or `printed_check`. `null` where none was recorded.",
            "nullable": true
          },
          "dealId": {
            "type": "string",
            "description": "The deal this transaction belongs to, if any",
            "nullable": true
          },
          "counterparty": {
            "$ref": "#/components/schemas/WalletCounterpartyV2"
          }
        },
        "required": [
          "id",
          "walletId",
          "type",
          "status",
          "direction",
          "amount",
          "currency",
          "createdAt",
          "completedAt",
          "eta",
          "network",
          "dealId",
          "counterparty"
        ]
      }
    }
  }
}