PrivateAuto Partner API (Beta) (2.0.0)

Download OpenAPI specification:

Beta. Not all endpoints are fully tested and verified; use caution with production deployments.

build 2026.1117.5604-4b55b28d0e

Partner integration API for DealNow initiation, lead ingestion, partner-scoped read access, and real-time webhook notifications.

Choosing an entry point

There are two ways to bring a seller to PrivateAuto. Which one fits depends on one question: has your flow already produced a firm price?

Lead — POST /v2/leads Offer — POST /v2/offers
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
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
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
Scope leads:write deal-invites:write
Idempotency callerReferenceId is required callerReferenceId is optional, and recommended
Webhooks None yet — poll GET /v2/leads?callerReferenceId=… offer.*, then deal.* and document.* once the deal opens

POST /v2/deal-invites is the deprecated alias of POST /v2/offers: same request, same response, same scope. It answers with Deprecation: true and a Link header naming /v2/offers. New integrations should call /v2/offers.

Not yet available. Plan around these rather than building toward them:

  • A lead does not link to the offer the dealer later sends, and there are no lead.* webhooks. You can see a lead's status change, but not which offer or deal it became.
  • Offers are delivered by link — returned to you, and emailed if you ask. They are not sent by SMS.
  • There is no v2 route that looks a dealer up by a user's email.

Your organization

"Your organization" below means everything your credential's own organization covers. A credential on a dealer group's root covers the root and every one of the group's locations: it reads their vehicles, deals and offers, and may act for any of them where a route names or reaches a location's record. One exception: POST /v2/vehicles always lists the vehicle under the credential's own organization, since the request has no field to name a location. A credential on a location covers that location only, never its parent or another location.

Who is who on an offer

POST /v2/offers takes a vin, a price in US dollars (not cents), and the parties. Your account is always one side of the offer. Say which side with partnerSide (buyer or seller), and name the other party under counterparty (email, optional name, and sendLink: true to have PrivateAuto email them their link):

{ "vin": "1HGBH41JXMN109186", "price": 18500, "partnerSide": "buyer",
  "counterparty": { "email": "seller@example.com", "sendLink": true } }

To start the deal for a dealership rather than your own organization, name it with dealerOrganizationId, or with dealerExternalId (your own identifier for it, as GET /v2/dealers shows). It must be your organization (a group root's credential may name one of its locations) or a dealership linked to your account, otherwise 403 dealer_not_authorized. The email on your own side (buyerEmail when you are the buyer) may name the user acting for you, and must belong to that dealership.

amount is the deprecated name for price. The older form still works: without partnerSide, the emails (buyerEmail, sellerEmail) decide which side you are on:

You send Your side
sellerEmail only, naming someone outside your organization You are the buyer; the email names the seller you are inviting
buyerEmail only, naming someone outside your organization You are the seller; the email names the buyer you are inviting
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
Neither You are the buyer; deliver the seller link yourself

Both emails naming people outside your organization is rejected with 400: the API does not start deals where you are not a party. A new field sent with its old counterpart must agree, or the request is rejected with 400 (price_conflict, counterparty_conflict).

If the VIN is not already listed under your account, year, make and model are required with it. Without sendLink (or, in the older form, sellerSendLink / buyerSendLink), deliver the returned link yourself.

Worked examples

Each example names the credential, the calls in order, and the webhooks to subscribe to. Scopes marked granted are not part of the default set — ask PrivateAuto to add them (see Scopes). Managing webhook endpoints yourself needs webhooks:manage, and reading the catalog or listing endpoints needs webhooks:read. Both are granted, so every "subscribe to" line below assumes them.

Website vendor — "sell us your car" form

  • Credential: partner JWT or organization API key. Scopes: leads:write (default).
  • Calls: POST /v2/leads with the dealer's organizationId, the prospect under contact, the car under vehicle, and your form submission id as callerReferenceId. Then GET /v2/leads?callerReferenceId=… to follow its status (new, contacted, qualified or closed).
  • Webhooks: none — there are no lead events yet.
  • You can submit leads for your own organization (a group root's credential also for each of its locations), and for a dealership PrivateAuto has associated with your account for lead submission. Any other organizationId is refused with 403; a location's credential cannot submit for its parent or another location.

Appraisal tool that shows a range

The same as the website vendor: a range is not a firm price, so send a lead and let the dealer price it. 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 below.

Instant-offer platform — the seller clicked Accept

  • Credential: partner JWT or organization API key. Scopes: deal-invites:write (default); deals:read and documents:read (default) to read the deal afterwards.
  • Calls:
    1. POST /v2/offers with vin, price, partnerSide: "buyer", the seller under counterparty with sendLink: true, and your quote id as callerReferenceId. Store the returned offerId and guid; dealId is null.
    2. Wait for deal.created, or poll GET /v2/deals?callerReferenceId=….
    3. GET /v2/deals/{dealId} and GET /v2/deals/{dealId}/documents as the deal progresses.
  • Webhooks: offer.accepted, offer.rejected, deal.created, document.completed, deal.payment_initiated, deal.payment_acknowledged, deal.completed, deal.cancelled, deal.expired. See Event sequences under Webhooks for the order they arrive in.
  • If you buy on behalf of dealers, name the dealership with dealerExternalId or dealerOrganizationId, and send the dealer user's email as buyerEmail. The deal is started for that dealership. A dealership becomes linked when it approves your OAuth application and that credential is first used, or when PrivateAuto links it for you.

CRM or DMS — a price agreed by phone

  • Credential: partner JWT or organization API key. Scopes: deal-invites:write, deals:read, documents:read, documents:write (default); deals:write (granted) to confirm title or cancel from your system.
  • Calls:
    1. POST /v2/offers with the agreed price, partnerSide (buyer or seller), the customer under counterparty with sendLink: true, and your CRM record id as callerReferenceId. Retrying with the same callerReferenceId, VIN and emails returns the original offer and sends nothing twice.
    2. GET /v2/deals?callerReferenceId=… to find the deal once the customer accepts.
    3. POST /v2/deals/{dealId}/documents to attach your paperwork; GET /v2/deals/{dealId}/documents to collect signed copies.
    4. With deals:write: POST /v2/deals/{dealId}/title/confirm, POST /v2/deals/{dealId}/cancel.
  • Webhooks: deal.* and document.*; add offer.* to see declines and withdrawals before a deal exists.

Embedded widget on your website

  • Credential: your publishable key in the X-PA-Widget-Key header — no Authorization header. Requests are accepted only from the website origins PrivateAuto has configured for your account. Scope: deal-invites:write (default).
  • Calls: POST /v2/offers/widget from the browser. It takes the older body only: amount rather than price, at most one of buyerEmail / sellerEmail to name the visitor, and no callerReferenceId. partnerSide, counterparty, dealerOrganizationId, dealerExternalId and price are rejected with 400, because a publishable key cannot vouch for a side or a dealership. No email is sent: show the returned link to the visitor.
  • Limits: 10 requests per minute per client IP.
  • Webhooks: subscribe from your server, as for POST /v2/offers.

Sourcing or AI buying agent

  • Credential: partner JWT or organization API key. Scopes: marketplace:search (granted).
  • Calls: GET /v2/marketplace/vehicles to search every vehicle publicly listed for sale.
  • Not yet available: making an offer on a vehicle found this way. Search results do not identify the seller, and POST /v2/offers starts its own transaction rather than reaching the seller of an existing marketplace listing. Use POST /v2/offers only when your agent already has the seller's email.

Auction — dealer to dealer

  • Credential: partner JWT or organization API key. Scopes: deal-invites:write (default).
  • Calls: POST /v2/offers with partnerSide, the dealership you act for in dealerExternalId or dealerOrganizationId, its user's email on your side (buyerEmail or sellerEmail), and the other dealer under counterparty. This works when both dealerships are linked to your account: the one you name is yours.
  • In the older form, without partnerSide or a named dealership, the emails decide: exactly one of them may belong to your organization or a linked dealership. If both do, the request is rejected with 400 and code: ambiguous_dealership_both_parties. A user who belongs to several linked dealerships is rejected with ambiguous_dealership_multiple_orgs; name the dealership to resolve either.
  • Webhooks: as for the instant-offer platform.

Read-only reporting for a dealer (OAuth)

  • Credential: an OAuth token the dealer approved (see Authentication). It holds at most deals:read and vehicles:read, and reads the dealer's organization and its locations.
  • Calls: GET /v2/deals, GET /v2/offers, GET /v2/vehicles, then the single-record reads for detail. GET /v2/me confirms the token works and shows the scopes it holds, but it reports your partner identity, not the dealer's organization.
  • Webhooks: a delegated token cannot manage webhooks. With your own credential, subscribe to dealer.linked and dealer.unlinked to learn when a dealer's approval takes effect or is revoked. Deal, offer and vehicle events for the dealer's own activity are not delivered to you: poll the reads.

Identifiers

Four identifiers follow an offer from the moment you send it to the closed deal. Store all four.

Identifier What it is Where it appears When it is set
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
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
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
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

Rules that follow from this:

  • Branch on dealId being null. An offer is not a deal. Do not fetch /v2/deals/{dealId} with an offerId — it returns 404.
  • Use guid to join an offer to its deal if you missed deal.created: both carry it.
  • callerReferenceId makes POST /v2/offers safe to retry. Sent again with the same VIN, buyer email and seller email, it returns the original offer and changes nothing — no terms rewritten, no email sent. Sent with a different VIN or emails, it is rejected with 409 and error: duplicate_reference, carrying the existing offerId. It is printable ASCII with no spaces, 1–128 characters, unique within your account.

Leads have their own pair: POST /v2/leads returns a leadId, and its required callerReferenceId is the key for GET /v2/leads. A lead's ids are not linked to any offer or deal.

Quickstart

  1. Get a Sandbox credential. Ask PrivateAuto for a Sandbox partner secret or organization API key. Build against the Sandbox first.

  2. Check who you are. GET /v2/me needs no scope, so it is the cheapest way to prove the credential works and to see what it may do:

    curl "https://partner-api.padev.xyz/v2/me" \
      -H "Authorization: Bearer $CREDENTIAL"
    
    {
      "partnerId": "acme-motors",
      "name": "Acme Motors",
      "organizationId": "663a1f4d6fae0c003456abcd",
      "scopes": ["deals:read", "vehicles:read", "documents:read", "documents:write", "deal-invites:write", "leads:write"],
      "apiVersion": "2.0.0"
    }
    

    Check scopes at startup, so a missing scope fails loudly there rather than as a 403 later.

  3. Make your first call. Pick the entry point that fits your flow (see Choosing an entry point):

    # A lead: no firm price yet
    curl -X POST "https://partner-api.padev.xyz/v2/leads" \
      -H "Authorization: Bearer $CREDENTIAL" -H "Content-Type: application/json" \
      -d '{"callerReferenceId":"LDR-0001","organizationId":"663a1f4d6fae0c003456abcd",
           "contact":{"name":"Jane Smith","email":"jane@example.com"},
           "vehicle":{"vin":"1HGBH41JXMN109186","year":2019,"make":"Honda","model":"Accord"}}'
    
    # An offer: the price is agreed
    curl -X POST "https://partner-api.padev.xyz/v2/offers" \
      -H "Authorization: Bearer $CREDENTIAL" -H "Content-Type: application/json" \
      -d '{"vin":"1HGBH41JXMN109186","year":2019,"make":"Honda","model":"Accord",
           "price":18500,"partnerSide":"buyer","counterparty":{"email":"seller@example.com"},
           "callerReferenceId":"QUOTE-0001"}'
    
  4. Subscribe to events. With webhooks:manage, register an endpoint, set its subscriptions, send it a test event, then verify it — see Webhooks.

Requests are JSON. A field the endpoint does not define is rejected with 400, so send only documented fields.

Sandbox

The Sandbox is PrivateAuto's test environment. Build and test your integration there before you point it at production.

Environment API host
Sandbox https://partner-api.padev.xyz
Production https://partner-api.privateauto.com

Setting up:

  1. Ask PrivateAuto for Sandbox credentials and for any granted scopes you need (see Scopes). Confirm them with GET /v2/me.
  2. Use your own test addresses for the counterparty and for buyerEmail / sellerEmail. An offer with counterparty.sendLink (or sellerSendLink / buyerSendLink) set can send a real email to the address you give.
  3. Register a webhook endpoint that the Sandbox can reach over public HTTPS. Private and internal addresses are rejected in every environment.
  4. Check what the Sandbox serves rather than assuming it matches production, or this page. The documentation can describe a newer build than the environment in front of you — see Availability by release. GET /api/docs-json returns the spec the environment is actually serving.

Ids, endpoints and webhook subscriptions do not carry over between the Sandbox and production: set them up again when you go live. If you use OAuth, the authorization and token endpoints also differ between the two — take each from what PrivateAuto sends you.

Offer actions on an existing deal (POST /v2/deals/{dealId}/offers and its accept, decline and withdraw routes) answer 503 with code: deal_first_not_enabled in an environment where they are not live yet. Check before relying on them in either environment.

Authentication

Every v2 request carries a credential in the Authorization header. Unlike v1, v2 takes your identity from the credential itself — there is no {partnerId} in any v2 path, and nothing you send in the URL or body changes which partner you are.

Three credential types are supported. OAuth is dealer-delegated and works differently from the other two — read its section before building against it.

Credential Send as Status
Partner JWT (HMAC) Authorization: Bearer <jwt> Available — what v1 partners already use
Organization API key Authorization: Bearer <key> Available
OAuth (dealer-approved) Authorization: Bearer <jwt> Available — read-only, and enabled per integration

Both available types resolve to the same partner identity and the same scopes, so an integration can move from one to the other without changing a single request.

Partner JWT (HMAC)

The token must be a HS256, HS384 or HS512 JWT signed with your partner shared secret, which PrivateAuto provides during onboarding.

Your shared secret is delivered base64-encoded — decode it to a UTF-8 string before signing. The payload must include p (your partner identifier) and must include exp; we recommend five minutes or less.

exp is required in v2. v1 accepts a token without one, which is a bearer credential that never ages out. If your v1 signing code omits exp, add it before you migrate — everything else about your tokens is unchanged.

The signing algorithm is pinned to the one on your partner record, not to the one in the token header, so changing alg in a token does not change how it is verified.

Node.js (npm install jsonwebtoken):

JWT=$(node -e '
  const jwt = require("jsonwebtoken");
  const secret = Buffer.from("YOUR_BASE64_SECRET", "base64").toString("utf-8");
  console.log(jwt.sign(
    { p: "YOUR_PARTNER_ID", iat: Math.floor(Date.now() / 1000) },
    secret,
    { algorithm: "HS256", expiresIn: "5m" }
  ));
')

Python (pip install pyjwt):

JWT=$(python3 -c '
import base64, jwt, time
secret = base64.b64decode("YOUR_BASE64_SECRET").decode("utf-8")
now = int(time.time())
print(jwt.encode(
    {"p": "YOUR_PARTNER_ID", "iat": now, "exp": now + 300},
    secret,
    algorithm="HS256",
))
')

CLI (jwt-cli, brew install mike-engel/jwt-cli/jwt-cli):

SECRET=$(printf '%s' 'YOUR_BASE64_SECRET' | base64 -d)
JWT=$(jwt encode \
  --alg HS256 \
  --secret "$SECRET" \
  --exp '+5m' \
  -P p=YOUR_PARTNER_ID)

Organization API key

An API key is an opaque string — not a JWT — issued by PrivateAuto for your organization. Send it as the bearer value exactly as delivered; there is nothing to sign and no expiry to manage per request:

KEY=$(cat /path/to/your/api-key)   # keep it out of your shell history
curl "https://partner-api.privateauto.com/v2/me" \
  -H "Authorization: Bearer $KEY"

Three things are worth knowing before you choose it over a JWT:

  • Scopes are intersected on every request. A key carries its own permissions, and what it may actually do is those permissions intersected with your partner grant, recalculated on every request. A key issued while you held a wider grant does not keep the wider access. A key issued with no permissions authenticates successfully and reaches only routes that require no scope — GET /v2/me will show you an empty scopes array rather than failing.
  • Revocation is not instantaneous. A successful validation is trusted for up to 60 seconds, so a revoked key may keep working for that long. Treat it as a minute, not as immediate.
  • Keys are long-lived. They do not rotate themselves. Rotate on your own schedule, and ask PrivateAuto to revoke the old key once the new one is in service.

OAuth (dealer-delegated)

The other two credentials are you, acting as yourself. OAuth is different: a dealer authorises your application to read their data, and your token acts on that dealer's behalf. Use it when your product works with dealers who are not you.

It is enabled per integration, not self-service. PrivateAuto registers your OAuth application against your partner account first. Until that exists, a token from it is rejected with the same 401 as any other unknown credential — there is nothing to probe, so if you are building against this, talk to your PrivateAuto contact before you start.

Getting a dealer connected

PrivateAuto registers your application and gives you four things: a client id, the redirect URI we registered for you, and the environment's authorization and token endpoints. Those endpoints are not on the API host — they belong to the identity provider, and they differ between the Sandbox and production, so take them from what we send you rather than deriving them from the API URL.

The flow is standard OAuth 2.0 authorization code with PKCE. Your application is a public client: there is no client secret, and PKCE is what takes its place, so it is required rather than optional.

  1. Send the dealer to the authorization endpoint with your client_id, your registered redirect_uri, response_type=code, a state value you generate, and a PKCE code_challenge (with code_challenge_method=S256).
  2. The dealer signs in and chooses an organization. If they belong to more than one they are shown a picker and pick one — you do not choose for them, and you cannot pass one in. Whichever they choose is the organization your token will read.
  3. They approve your application, and we redirect back to your redirect_uri with code and your state. Check the state matches before going further.
  4. Exchange the code at the token endpoint for an access token and a refresh token, sending the code_verifier that matches the challenge from step 1.
  5. Call the API with Authorization: Bearer <access token>, and confirm with GET /v2/me that the scopes are what you expect before running real traffic.

Two things that catch people out:

  • Keep the code_verifier for the exchange. It is generated in step 1 and needed in step 4. If your callback handler runs in a different process from the one that built the authorization URL, the verifier has to survive that hop — and an authorization code is single-use and short-lived, so losing it means sending the dealer through consent again.
  • Refresh tokens rotate. Every refresh returns a new refresh token and invalidates the one you sent. Store the new one before you use the access token, or the next refresh fails and the dealer has to reconnect.

What a delegated token can do

Read-only, and narrower than your own credential. A delegated token may hold only deals:read and vehicles:read, intersected with what your partner account already holds — it can never gain a capability you do not have, and it can never write, publish, manage dealers or manage webhooks. If you need to act on a dealer's behalf beyond reading, that is a conversation to have with us rather than a scope to request.

Check GET /v2/me as always: it reports the scopes the token actually holds, which for a delegated credential will be a subset of your account's.

Whose data it reads

The dealer's, not yours. When a dealer approves your application they choose an organization, and your token reads that organization and its locations — a dealer group, not a single rooftop, because that is the unit the consent screen presents. Your own inventory and deals are not visible through a delegated token; use your partner JWT or API key for those.

Revocation — read this before you design your token handling

A dealer can withdraw consent at any time. When they do:

  • Refreshing stops immediately. Your next refresh exchange fails.
  • An access token already issued keeps working until it expires, which can be up to 24 hours.

That is a property of the identity provider, not a choice we made, and it is why the recommendation below matters: refresh often and treat the access token as short-lived, even though its exp says otherwise. Refresh tokens rotate on every exchange, so always store the new one and discard the old.

PrivateAuto can also disable your OAuth client outright, which takes effect on the next request rather than at token expiry. We will do that if a dealer reports a problem.

Making an authenticated request

curl "https://partner-api.privateauto.com/v2/me" \
  -H "Authorization: Bearer $CREDENTIAL"

GET /v2/me takes no scope and is the cheapest way to confirm a credential works. It reports your partner id, the organization the credential acts as, and every scope it holds — check that at startup, so a missing scope fails loudly at boot rather than as a 403 in production.

When authentication fails

  • 401 — the credential was rejected. The body is deliberately identical for every cause (unknown partner, bad signature, missing or past exp, unknown or revoked key, a key belonging to no partner), because a response that told them apart would let a caller enumerate partners and organizations. Do not parse it; re-check the credential itself.
  • 403 — the credential is valid but lacks the scope the route requires. Compare what GET /v2/me reports against the scope named on the endpoint.
  • 503 with Retry-After — credential verification is temporarily unavailable. This is not a verdict on your credential and rotating it will not help. Back off for the advertised number of seconds and retry.

Production host: https://partner-api.privateauto.com. Sandbox host: https://partner-api.padev.xyz (see Sandbox).

Scopes

Every v2 route names the scope it requires; a credential without it gets 403 with Missing required scope: <scope>. GET /v2/me requires none and lists the scopes your credential holds.

Default scopes are what an account has when PrivateAuto has not set an explicit list for it — the same capabilities v1 offers. Granted scopes are never part of the default: ask PrivateAuto to add them. Once your account has an explicit list, that list is exactly what you hold.

Scope Unlocks
deals:read GET /v2/deals, GET /v2/deals/{dealId}, GET /v2/offers, GET /v2/offers/{offerId}. Subscribing to deal.*, offer.* and dealer.* events Default
deals:write POST /v2/deals/{dealId}/title/confirm, POST /v2/deals/{dealId}/services, POST /v2/deals/{dealId}/cancel Granted
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
offers:write Acting on the live offer of an existing deal: POST /v2/deals/{dealId}/offers (counter), and .../accept, .../decline, .../withdraw Granted
leads:write POST /v2/leads and GET /v2/leads — the lookup needs it too Default
vehicles:read GET /v2/vehicles, GET /v2/vehicles/{vehicleId}, GET /v2/vehicles/{vehicleId}/photos. Subscribing to listing.* events Default
vehicles:write POST /v2/vehicles; changing the price, taking a vehicle off the market and putting it back; adding, removing and ordering photos Granted
vehicles:publish POST /v2/vehicles/{vehicleId}/listing/publish — puts a vehicle on the public marketplace, which is billable Granted
marketplace:search GET /v2/marketplace/vehicles Granted
documents:read GET /v2/deals/{dealId}/documents, GET /v2/documents/{documentId}, GET /v2/generated-documents/{documentId}. Subscribing to document.* events Default
documents:write POST /v2/deals/{dealId}/documents, DELETE /v2/documents/{documentId} Default
webhooks:read GET /v2/webhooks/endpoints, GET /v2/webhooks/endpoints/{endpointId}, GET /v2/webhooks/catalog Granted
webhooks:manage Registering, changing, verifying, testing, pausing and removing endpoints; rotating secrets; editing subscriptions; GET /v2/webhooks/deliveries Granted
dealers:manage GET /v2/dealers, GET /v2/dealers/{externalId} Granted
reports:read GET /v2/reports, GET /v2/reports/{shareId} Granted
wallet:read GET /v2/wallets and the wallet and transaction reads under it Granted

GET /v2/me can also list dealers:lookup. No v2 route uses it.

What a credential actually holds depends on its type as well as your account:

  • Partner JWT — your account's scopes.
  • Organization API key — the key's own permissions intersected with your account's scopes, recalculated on every request.
  • OAuth (dealer-delegated) — at most deals:read and vehicles:read, intersected with your account's scopes.
  • Widget publishable key — used only by POST /v2/offers/widget, which checks your account holds deal-invites:write.

Examples

Abbreviated: each endpoint's reference below lists every field.

Send an offer

POST /v2/offers — you are buying, so the counterparty is the seller:

{
  "vin": "1HGBH41JXMN109186",
  "year": 2019,
  "make": "Honda",
  "model": "Accord",
  "price": 18500,
  "partnerSide": "buyer",
  "counterparty": { "email": "seller@example.com", "name": "John Doe", "sendLink": true },
  "callerReferenceId": "QUOTE-0001"
}

201 Created:

{
  "offerId": "64a1f2e3b5c8d90012345678",
  "dealId": null,
  "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
  "callerReferenceId": "QUOTE-0001",
  "buyerLink": "https://…",
  "sellerLink": "https://…"
}

The same request sent again returns this same body, with dealId filled in once the seller has accepted. The same callerReferenceId with a different VIN or email returns 409:

{
  "error": "duplicate_reference",
  "message": "callerReferenceId is already used for an invitation with a different VIN, buyer email or seller email",
  "offerId": "64a1f2e3b5c8d90012345678"
}

Read the deal once the seller accepts

GET /v2/deals?callerReferenceId=QUOTE-0001, or GET /v2/deals/{dealId} with the id from deal.created:

{
  "id": "64a1f2e3b5c8d90012345679",
  "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
  "status": "active",
  "offerId": "64a1f2e3b5c8d90012345678",
  "currentOfferStatus": "accepted",
  "callerReferenceId": "QUOTE-0001",
  "amount": 18500,
  "closingStatus": "none",
  "documentsStatus": "pending"
}

List reads are paged with _page (from 0) and _limit, and return { "data": [...], "_meta": { "page", "limit", "total", "hasMore" } }.

Submit a lead

POST /v2/leads:

{
  "callerReferenceId": "LDR-0001",
  "organizationId": "663a1f4d6fae0c003456abcd",
  "leadCode": "TRADE_IN",
  "contact": { "name": "Jane Smith", "email": "jane@example.com", "phone": "555-867-5309" },
  "vehicle": { "vin": "1HGBH41JXMN109186", "year": 2019, "make": "Honda", "model": "Accord", "mileage": 42000 }
}

201 Created:

{
  "leadId": "663c3f4d6fae0c003456cdef",
  "callerReferenceId": "LDR-0001",
  "status": "new",
  "createdAt": "2026-11-13T14:22:00.000Z"
}

Sending the same callerReferenceId again returns 409 with the lead you already created:

{ "error": "duplicate_reference", "leadId": "663c3f4d6fae0c003456cdef", "callerReferenceId": "LDR-0001" }

A webhook delivery

deal.created, as posted to your endpoint:

{
  "id": "64a1f2e3b5c8d90012345679",
  "eventId": "a2f1e9c4b7d8…",
  "eventKey": "…",
  "status": "active",
  "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
  "amount": 18500,
  "buyerId": "64a1f2e3b5c8d90012340001",
  "sellerId": "64a1f2e3b5c8d90012340002",
  "callerReferenceId": "QUOTE-0001"
}

Status values

Offer and deal statuses are closed lists: a value outside the list is reported as null rather than passed through. Lead and listing statuses are reported as stored. Either way, treat a value you do not recognise as something to log, not to fail on.

Offer — status on GET /v2/offers, and currentOfferStatus on a deal:

Value Meaning
pending On the table, waiting for the other side
accepted Accepted — this is the offer that opened the deal
countered Replaced by a counter-offer
declined Declined by the side it was sent to. The event is offer.rejected
deleted Withdrawn by the side that made it. The event is offer.cancelled

Deal — status on GET /v2/deals:

Value Meaning
pending Created, not yet active
active In progress: the parties are working through title, documents and payment
sold Completed. The event is deal.completed
cancelled Cancelled by a party. The event is deal.cancelled
expired Lapsed without completing. The event is deal.expired

Inside an active deal, closingStatus tracks the money — none, ready, initiated, acknowledged — and documentsStatus the paperwork — empty, pending, complete. Each party's status is invited, joined or readyToClose.

Lead — status on POST /v2/leads and GET /v2/leads:

Value Meaning
new Received; every lead starts here
contacted The dealer has contacted the prospect
qualified The dealer has qualified the lead
closed The dealer has closed the lead

Vehicle listing — listing.status on GET /v2/vehicles:

Value Meaning
pending Created but not on the marketplace. POST /v2/vehicles creates listings here, and reactivating returns one here
live Published on the marketplace
sold Sold
deactivated Taken off the market
expired Lapsed. Reactivate it to list it again
expiredGrace Lapsed, like expired, and handled the same way: reactivate it to list it again
purchased A vehicle your organization bought through PrivateAuto, rather than one you listed. Filter with ownership=purchased
removed Taken down by your organization. Returned when you omit ownership, left out by ownership=listed. Filter with status=removed and no ownership

Errors

Errors are JSON. Most have the shape { "statusCode": 400, "message": "…", "error": "Bad Request" }, where message is a string, or an array of strings for a request that failed validation. Where a failure has a machine-readable code, it is in code or — for the older codes marked (error) in the table — in error. Branch on the code, never on message text.

Status Meaning
400 The request is malformed: a missing or invalid field, a field the endpoint does not define, or one of the 400 codes below
401 The credential was rejected. The body is identical for every cause — see Authentication
402 The dealership has no active PrivateAuto business subscription: publishing a vehicle, or starting an offer with POST /v2/offers — see subscription_inactive below
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)
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
409 The request conflicts with the record's current state — see the codes below
413 An uploaded document is too large
429 A rate limit was hit — see Rate limits
503 Temporarily unavailable. Honour Retry-After when present, and retry
Code Status When
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
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
price_conflict 400 POST /v2/offers: price and the deprecated amount both sent, with different values
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)
dealer_attribution_conflict 400 POST /v2/offers: dealerOrganizationId and dealerExternalId name different dealerships
unknown_event 400 Subscribing to an event name that does not exist. events lists them
invalid_url, insecure_transport, credentials_in_url, private_destination, unresolvable_host 400 A webhook endpoint URL that is not a public HTTPS address
passcode_required 401 Reading a report link that is protected by a passcode
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
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
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
event_not_entitled 403 Subscribing to events your scopes do not cover. events lists them
duplicate_reference (error) 409 A callerReferenceId reused with different content: on POST /v2/offers (carries offerId), POST /v2/leads (carries leadId; any reuse) or a document upload (a different file)
competing_active_deal 409 Accepting an offer when another deal on the same vehicle is already active
invalid_transition 409 Countering, accepting, declining or withdrawing an offer that is not in a state that allows it
deal_not_cancellable 409 Cancelling a deal that can no longer be cancelled
deal_not_uploadable (error) 409 Uploading a document to a cancelled or expired deal
document_acted_on (error) 409 Removing a document that has already been signed or acknowledged
photo_set_mismatch (error) 409 Reordering photos with a list that is not exactly the vehicle's current photos
endpoint_exists 409 Registering a webhook URL you have already registered, or changing an endpoint to one
endpoint_limit_reached 409 Registering more than 10 webhook endpoints
endpoint_unverified 409 Enabling or disabling an endpoint that has never been verified
no_challenge_outstanding, challenge_superseded 409 Verifying an endpoint with no current challenge, or whose challenge changed mid-verification. Request verification again
rate_limit_exceeded (error) 429 POST /v2/leads, or webhook verify/test. retryAfterMs says how long to wait
auth_unavailable 503 Credential checking is temporarily unavailable — not a verdict on your credential. Sent with Retry-After
deal_first_not_enabled 503 Offer actions on an existing deal are not live in this environment yet

Rate limits

Route Limit Counted per
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
POST /v2/offers, POST /v2/deal-invites No route-specific limit —
POST /v2/offers/widget, POST /v2/deal-invites/widget 10 per minute Client IP, per route
Webhook POST .../verify and POST .../test together 10 per minute Your partner account
GET /v2/reports, GET /v2/reports/{shareId} 30 per minute Client IP

Each limit applies over a one-minute window. POST /v2/leads and webhook verify/test send X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds at which capacity next returns) — verify/test on every response, leads only on success. Their 429 body carries retryAfterMs, the wait in milliseconds before capacity returns; pace retries off that.

{ "statusCode": 429, "error": "rate_limit_exceeded", "message": "Rate limit exceeded: 60 requests per minute", "retryAfterMs": 41250 }

The counters are kept by each API server rather than shared between them, so you may occasionally get more than the stated limit through. Design for the stated number.

POST /v2/offers having no specific limit is not an invitation to burst: send each offer once, and use callerReferenceId so a retry is safe rather than sending a second offer.

Webhooks

PrivateAuto posts an event to your server whenever something happens to an offer, deal, document, vehicle listing or dealer link that your integration can see.

In v2 you set webhooks up yourself: register an endpoint, choose the events it receives, verify it, and rotate its secret through /v2/webhooks/*. Listing endpoints and reading the catalog need the webhooks:read scope; managing endpoints and reading the delivery log need webhooks:manage. Neither is a default scope — ask PrivateAuto to grant both (see Scopes).

Already receiving webhooks from a v1 integration? That configuration keeps delivering until you verify a v2 endpoint. Read Coming from v1 under Configuration before you start.

Reading this against a specific environment? This page can describe a newer build than the one you are calling. See Availability by release for how to check.

Configuration

Operation Endpoint
Register an endpoint POST /v2/webhooks/endpoints
List / inspect GET /v2/webhooks/endpoints · GET /v2/webhooks/endpoints/{endpointId}
Update PATCH /v2/webhooks/endpoints/{endpointId}
Remove DELETE /v2/webhooks/endpoints/{endpointId}
Pause / resume delivery POST .../disable · POST .../enable
Issue a new signing secret POST .../rotate-secret
Prove ownership POST .../verify
Send a synthetic event POST .../test
See what was delivered GET /v2/webhooks/deliveries · GET /v2/webhooks/deliveries/{logId}

Subscriptions are managed per endpoint:

Operation Endpoint
Replace the whole set PUT /v2/webhooks/endpoints/{endpointId}/subscriptions
Add to the set POST /v2/webhooks/endpoints/{endpointId}/subscriptions
Remove one event DELETE /v2/webhooks/endpoints/{endpointId}/subscriptions/{event}
Clear every subscription DELETE /v2/webhooks/endpoints/{endpointId}/subscriptions

Reading endpoints and the catalog needs webhooks:read; everything else here, including the delivery log, needs webhooks:manage.

You may register up to 10 endpoints, each with its own subscription set and its own secret — a delivery fans out to every active endpoint subscribed to that event. Each delivery carries its own idempotency identifier, so two endpoints receiving the same event are two distinct deliveries.

Setting up an endpoint, in order:

  1. POST /v2/webhooks/endpoints with your URL. It starts unverified, and only active endpoints receive events.
  2. Set its subscriptions.
  3. POST .../test to confirm it accepts a delivery and your signature check passes.
  4. POST .../verify to prove you control the URL. The endpoint becomes active.

Testing an endpoint

POST .../test sends a synthetic endpoint.test event signed exactly like a real delivery — the same sha256= signature, timestamp format and headers — so a receiver that passes it will verify real traffic. It works on an unverified endpoint, which makes it the tool for working out why verification is failing.

verify is different: the challenge is unsigned. It proves you control the URL, not that your signature check works. Answer it with a 2xx whose body contains the challenge value.

verify and test both make PrivateAuto call your URL, and together they are limited to 10 requests per minute per partner. Beyond that they answer 429; the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers say when capacity returns.

Rotating a signing secret

POST .../rotate-secret returns a new secret once. Deliveries may be signed with the new secret from the moment the call returns, and all of them are within 5 minutes. None is signed with the old secret after previousSecretExpiresAt — 15 minutes after the call.

  • Your receiver must accept the new secret as soon as the call returns.
  • Load the secrets you accept from a store you read at request time (or hot-reload), so that storing the new secret makes it live without a redeploy.
  • Keep accepting the old secret until previousSecretExpiresAt, then remove it.
  • A delivery rejected before your receiver accepts the new secret is recorded as failed and retried on the usual schedule (1, 5 and 15 minutes); one that fails every retry is listed under GET /v2/webhooks/deliveries?status=dlq for you to reconcile.

What you may subscribe to

GET /v2/webhooks/catalog returns exactly the events your credential may subscribe to. Entitlement is derived from the scopes you already hold rather than maintained as a separate list, so it cannot disagree with what you can read:

Event namespace Requires
deal.*, dealer.*, offer.* deals:read
listing.* vehicles:read
document.* documents:read

* subscribes to everything, and needs all three scopes. Subscribing to an event outside your scopes is rejected with 403 and code: event_not_entitled; an event name that does not exist, with 400 and code: unknown_event. Read the catalog rather than hardcoding a list — it is the authoritative answer for your credential, and it is what the API enforces.

User events (user.registered) are not subscribable in v2: they carry a person's email address and name.

Endpoint requirements

Your endpoint URL must be public HTTPS. Private and internal addresses are rejected, including link-local metadata addresses, and the check is applied again at delivery time rather than only at registration — a hostname that resolves publicly when you register it and privately later does not become a way in.

Coming from v1

Delivery format, signature scheme, idempotency identifier and retry behaviour are unchanged — those belong to the delivery pipeline, not to the API version. Your existing endpoint keeps receiving events until you deliberately migrate.

Event names are unchanged too, unless you opt in. A managed endpoint that copies your v1 list, wildcards included, receives the same names v1 sends. Only an endpoint that lists a canonical name from Deprecations (for example offer.declined) receives that event under the canonical name. Wildcard subscriptions move to the canonical names at a cut-over date we will announce there. Your v1 configuration always receives the original names, including when delivery falls back to it because you no longer have an active managed endpoint.

Routing is either/or per partner, never both: while you have no active managed endpoint you are served from your v1 configuration, and as soon as you have one you are served from managed endpoints only. That is what stops a migrating partner receiving everything twice.

Verification is the cutover, not registration. A new endpoint starts unverified, and only active endpoints receive deliveries — so POST /v2/webhooks/endpoints on its own changes nothing. The moment you complete POST .../verify, that endpoint becomes active and your v1 endpoint stops receiving.

So follow the setup order above, and note at step 2 that subscriptions do not carry over. Your v1 event list is separate configuration; a managed endpoint starts with only what you give it, so verifying with an empty or partial set silently narrows your feed.

One event cannot be carried across: user.registered is not subscribable in v2. If you receive it today under your v1 configuration, verifying a managed endpoint ends it. Raise this with us before you migrate rather than after.

Two behaviours worth knowing because they are easy to be surprised by:

  • Disabling or deleting every managed endpoint puts you back on the v1 destination, because the fallback is chosen when no active endpoint exists.
  • That includes automatic disabling. An endpoint that fails enough consecutive deliveries is disabled for you — and if it was your only one, delivery reverts to your v1 endpoint rather than stopping. Watch GET /v2/webhooks/deliveries after cutover; a silent return to the old destination looks a lot like nothing having happened.

Delivery Format

Webhooks are delivered as POST requests with the following headers:

Header Description
Content-Type application/json
X-PA-Event Event type, e.g. deal.completed
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
X-PA-Signature HMAC-SHA256 signature (see Verifying Signatures)
X-PA-Partner Your partner ID
X-PA-Event-Id Stable per-event idempotency identifier (see Idempotency)
User-Agent PrivateAuto-Webhooks/1.0

Every payload also carries eventId and eventKey at the top level — see Idempotency.

Verifying Signatures

Every delivery includes an X-PA-Signature header of the form sha256={hex}. To verify:

  1. Extract X-PA-Timestamp from the request headers.
  2. Concatenate: {timestamp}.{raw_body}.
  3. Compute HMAC-SHA256 of that string using your webhook secret.
  4. Compare (hex-encoded) to the value after sha256= in X-PA-Signature.
  5. Reject the delivery if X-PA-Timestamp is more than 5 minutes from your own clock.

The timestamp is inside the signed material so that step 5 can stop a captured delivery being replayed later. Every attempt, including a retry, is signed with the time it was sent, so a 5-minute tolerance never rejects a legitimate delivery — allow more only if your clock is not NTP-synchronised.

const crypto = require('crypto');

function verifySignature(req, secret) {
  const timestamp = req.headers['x-pa-timestamp'];
  const received  = req.headers['x-pa-signature']; // "sha256=abc123..."
  const body      = req.rawBody;                   // raw bytes, not parsed JSON

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Always use the raw request body (before JSON parsing) for signature verification.

Idempotency

Every webhook payload carries two fields that let you safely dedupe duplicate deliveries:

Field Type Description
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).
eventKey string Composite key the eventId was derived from. Informational only — see warning below.

The same eventId value is also delivered as the X-PA-Event-Id HTTP header.

Recommended: keep a cache of received eventIds 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.

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.

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.

Retry Behavior

If your endpoint returns a non-2xx status, answers with a redirect, or does not respond within 10 seconds, PrivateAuto retries the delivery:

Retry When
1 1 minute after the first attempt
2 5 minutes after retry 1
3 15 minutes after retry 2

Each 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.

If 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.

Return 2xx as quickly as possible — process events asynchronously if needed.

Event Types

Subscribe to individual events or use wildcard namespaces:

Wildcard Matches
deal.* All deal events
dealer.* All dealer-link events
document.* All document events
listing.* All listing events
offer.* All offer events
* All events

Deal Events

Event When it fires
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
deal.completed The deal closes: payment is acknowledged and the vehicle is marked sold
deal.cancelled Either party cancels the deal
deal.expired The deal expires without completing
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
deal.terms_confirmed New name for deal.offer_accepted, same payload. Delivered only to an endpoint that lists it; see Deprecations
deal.buyer_joined The buyer signs in and joins the deal
deal.seller_joined The seller signs in and joins the deal
deal.buyer_ready The buyer marks "Ready to Close" after completing every required step
deal.seller_ready The seller marks "Ready to Close" after completing every required step
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
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
deal.title_approved The seller marks their uploaded title photos complete. Seller-driven, not a PrivateAuto review
deal.title_uploaded New name for deal.title_approved, same payload. Delivered only to an endpoint that lists it
deal.docs_submitted The parties have signed every required closing document, starting review
deal.docs_approved PrivateAuto approves the closing documents
deal.payment_initiated The buyer starts the payment transfer
deal.payment_acknowledged The seller acknowledges receiving the payment
deal.amount_changed The deal amount changes after the deal opened. Not sent when the deal is created
deal.negative_equity_identified PrivateAuto's payoff review finds the seller's loan payoff exceeds the deal amount
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
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
deal.negative_equity_funded The negative-equity balance has been paid
deal.loan_payoff_docs The seller uploads loan payoff documents (the first upload only)
deal.loan_payoff_confirmed PrivateAuto confirms the loan payoff
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'
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'

Deal event payload:

Field Type Description
id string The deal id — use it with GET /v2/deals/{dealId}
guid string The transaction's stable handle; the same as the offer's (see Identifiers)
status string Current deal status
amount number Deal amount in dollars
buyerId string Buyer's user id
sellerId string Seller's user id
negativeEquity boolean | null Whether the loan payoff exceeds the deal amount
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
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

Deal payloads do not carry a vin. Fetch GET /v2/deals/{dealId} for the deal's listingId, then GET /v2/vehicles/{vehicleId} with that id for the VIN and the full vehicle.

The events listed under documents above carry short-lived signed links to the files:

Field Type Description
documents[].filename string Original filename
documents[].signedUrl string Pre-signed HTTPS URL — fetch it before it expires
documents[].expiresAt string ISO 8601 time the link stops working: 4 hours after the event

Download the file promptly. To get fresh links later, call GET /v2/deals/{dealId}/documents.

deal.loan_payoff_docs and deal.loan_payoff_confirmed describe the seller's loan payoff rather than the deal itself: their id is not the deal id. Use their dealId.

deal.poa_approved and deal.bill_of_sale_approved describe a document, and carry the document payload below — id is the document, dealId the deal.

Document Events

These are the current per-document signature events. Prefer them over the deprecated deal-level deal.poa_approved / deal.bill_of_sale_approved events.

Event When it fires
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
document.completed Every required signer on a document has signed. Fires once per document, whatever its type
deal.document_uploaded A partner uploads a document to a deal with POST /v2/deals/{dealId}/documents

Tell document types apart by docClassification on the payload, not by event name.

Document event payload:

Field Type Description
id string The document id
dealId string The deal the document belongs to
status string Document status
docClassification string The document type, e.g. bill-of-sale, poa
signers array { signerRole, signedAt } for each signer — seller, buyer or coSeller
documents array Signed links to the file, as above (on the deprecated deal-level events)

Offer Events

Event When it fires
offer.created An offer is made — by POST /v2/offers, or by a buyer in the PrivateAuto app
offer.accepted The offer is accepted
offer.rejected The offer is declined. The offer's status reads declined
offer.declined New name for offer.rejected, same payload. Delivered only to an endpoint that lists it
offer.cancelled The offer is withdrawn by the side that made it. The offer's status reads deleted
offer.withdrawn New name for offer.cancelled, same payload. Delivered only to an endpoint that lists it

Offer event payload:

Field Type Description
id string The offer id — use it with GET /v2/offers/{offerId}
guid string The transaction's stable handle; the deal opened from this offer carries the same one
status string Current offer status
listingId string The vehicle the offer is for — use it with GET /v2/vehicles/{vehicleId}
amount number Offer amount in dollars
buyerId string The user who made the offer — named for the usual case, where the buyer makes it
sellerId string The user the offer was made to
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

Listing Events

Event When it fires
listing.created A vehicle listing is created
listing.updated A listing is edited in a way no more specific event below describes. One change produces at most one listing event
listing.published A listing goes live on the marketplace
listing.sold A listing is marked sold, by hand or when its deal completes
listing.deleted A listing is deactivated, expires or is deleted
listing.ownership_set The vehicle's ownership type (owned, financed or leased) is set by PrivateAuto
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
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

Listing event payload:

Field Type Description
id string The vehicle id — use it with GET /v2/vehicles/{vehicleId}
status string Current listing status
vin string Vehicle Identification Number
year number Vehicle model year
make string Vehicle make
model string Vehicle model
trim string Vehicle trim level
price number Listing price in dollars
sellerId string Seller's user id
ownershipType string owned, financed, or leased (when ownership is declared)
vehicleHaveLien boolean Whether the vehicle has an active lien

Dealer Events

Event When it fires
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
dealer.unlinked That standing was revoked. Offers you send afterwards are no longer started for that dealership

Delivered only to the partner the link belongs to — never to another partner linked to the same dealership. Your own organization is always linked and never produces these events. Further requests with the same OAuth credential do not re-send dealer.linked, and for OAuth, linkedAt is when PrivateAuto first saw the credential used, not when the dealer approved it.

Dealer event payload:

Field Type Description
id string The link's id
organizationId string PrivateAuto dealership id
partnerId string Your partner id
via string How the link was made: dealer-lookup, oauth-delegation or admin
credentialMode string How the request that made the link authenticated: hmac, api-key, m2m or oauth
clientId string | null OAuth links: the OAuth application the dealer approved
actingUserId string | null OAuth links: the user who approved it
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
linkedAt string ISO 8601 time the link was created
unlinkedAt string | null ISO 8601 time the link was revoked; null while linked
reason string | null Revocation reason, when one was recorded

Responding to Webhooks

  • Return any 2xx status to acknowledge receipt.
  • Return 2xx immediately and process the event asynchronously if your handler is slow.
  • Return 401 for signature failures so PrivateAuto can flag delivery issues.

Reading the full record

Payloads are deliberately compact. Use the webhook as the signal and the v2 read as the source of truth:

Event family Payload id Read the full record with
deal.* id (the deal) GET /v2/deals/{dealId}
offer.* id (the offer); listingId GET /v2/offers/{offerId}; GET /v2/vehicles/{vehicleId}
listing.* id (the vehicle) GET /v2/vehicles/{vehicleId}
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
deal.title_submitted, deal.title_approved id (the deal) GET /v2/deals/{dealId}/documents
deal.loan_payoff_docs, deal.loan_payoff_confirmed dealId GET /v2/deals/{dealId} and its documents
dealer.* organizationId No v2 read returns dealer links yet, so the payload is the record. Keep organizationId as the dealership's PrivateAuto id
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

That includes offers you send for a linked dealership: the reads return the offers and deals you started, their documents, and the vehicles you created or that belong to the dealership, although they belong to the dealership's organization.

Event sequences by transaction type

Which events arrive, and in what order, depends on which side you are on and how the deal started.

Who is on each side

Each deal is classified by whether a dealership is on each side — seller.organizationId and buyer.organizationId on the deal:

Seller is a dealership Buyer is a dealership Type Plain English
No No C2C Consumer sells to consumer
No Yes C2D A dealer buys from a consumer
Yes No D2C A dealer sells to a consumer
Yes Yes D2D Wholesale between two dealers

1. You are the buyer, and you sent the offer

The most common shape: you send POST /v2/offers naming the seller, and the seller accepts.

What happens                       Event delivered              Notes
─────────────────────────────────  ───────────────────────────  ─────────────────────────────────
POST /v2/offers                    listing.created              when a listing is created for
                                                                the vehicle
                                   offer.created                dealId is still null
─────────────────────────────────  ───────────────────────────  ─────────────────────────────────
the seller follows their link      offer.accepted
and accepts                        deal.created                 dealId now exists
─────────────────────────────────  ───────────────────────────  ─────────────────────────────────
each signer signs a document       document.signature_added     one per signer
the last signer signs              document.completed           once per document
                                   deal.bill_of_sale_approved   deprecated; Bill of Sale only
─────────────────────────────────  ───────────────────────────  ─────────────────────────────────
PrivateAuto approves the documents deal.docs_approved
─────────────────────────────────  ───────────────────────────  ─────────────────────────────────
you send the funds                 deal.payment_initiated
─────────────────────────────────  ───────────────────────────  ─────────────────────────────────
the seller confirms receipt        deal.payment_acknowledged
                                   deal.completed

Minimum subscription for this flow: deal.created, document.completed, deal.payment_initiated, deal.payment_acknowledged, deal.completed. Add offer.rejected, offer.cancelled, deal.cancelled and deal.expired to see it end early, and deal.docs_approved to mirror PrivateAuto's "all documents reviewed" state.

2. You are the buyer, and the seller listed in the app

The seller lists the vehicle on PrivateAuto, a buyer from your organization makes an offer in the app, and the seller accepts:

listing.created          the seller creates the listing (only if it was started through your integration)
listing.published        the seller publishes it
offer.created            your buyer makes an offer
offer.accepted           the seller accepts
deal.created             the deal opens
{ then the same documents / payment / completion chain as 1 }

3. You are the seller

The mirror image: you send POST /v2/offers naming the buyer, or a buyer makes an offer on a vehicle you listed.

listing.created              you create the listing
listing.published            it goes live
listing.ownership_set OR     the ownership type is set by PrivateAuto
  listing.ownership_submitted  or by you while listing
─────────────────────────────────────────────────────────────────────────
offer.created                the buyer makes an offer (or you send one)
offer.accepted               the offer is accepted (possibly after counters)
deal.created                 the deal opens
{ documents round — you sign the Bill of Sale, Power of Attorney and so on as the seller }
deal.docs_approved
deal.payment_initiated       the buyer sends the funds
deal.payment_acknowledged    you confirm receipt
deal.completed
listing.sold                 the listing is marked sold once the deal completes

4. D2D — dealer to dealer

Both sides are dealerships. You receive events for a deal when your organization is on either side, with the same set as C2D or D2C. If both organizations are yours you see both a listing.published (seller side) and an offer.created (buyer side) for the same deal: dedupe on the deal's guid.

5. C2C — consumer to consumer

You receive events only for offers and deals started through your integration, since neither party belongs to your organization. That needs your account's routing to include appSource (see Routing below).

Document signing, signer by signer

The Bill of Sale and Power of Attorney — and any other document PrivateAuto has signed in the app — each produce one document.signature_added per signer and one document.completed when the last signer is done:

seller signs          document.signature_added (signerRole: seller)
buyer signs           document.signature_added (signerRole: buyer)
                      document.completed           (every signer done)
                      deal.bill_of_sale_approved   (deprecated, Bill of Sale only)
                      deal.poa_approved            (deprecated, Power of Attorney only)

Each document.signature_added payload carries:

{
  "id": "<documentId>",
  "dealId": "<dealId>",
  "docClassification": "bill-of-sale",
  "signers": [{ "signerRole": "seller", "signedAt": "<ISO date>" }]
}

Branch on docClassification, not on the event name. The deprecated deal.bill_of_sale_approved and deal.poa_approved keep firing until 1 February 2027; see Deprecations.

When a deal has a co-seller, the Bill of Sale and Power of Attorney each gain a signer: document.signature_added fires three times (seller, co-seller, buyer) and document.completed once.

Negative equity

When the seller's loan payoff is more than the deal amount, PrivateAuto flags the deal negativeEquity: true and sends one of two events:

Event Reached when
deal.negative_equity_reported The deal amount is changed in the app and drops below the payoff
deal.negative_equity_identified PrivateAuto's payoff review finds it

Both carry negativeEquity: true; the event name is the only difference. deal.negative_equity_funded follows once the shortfall is paid.

Loan payoff documents

For a seller with an outstanding loan on the vehicle:

the seller uploads a payoff document  →  deal.loan_payoff_docs       (first upload only)
PrivateAuto confirms the payoff       →  deal.loan_payoff_confirmed

Documents on each type of deal

Document C2C C2D D2C D2D Notes
Title photos (front / back) ✅ ✅ ✅ ✅ Title information confirmed → deal.title_submitted; photos uploaded and marked complete → deal.title_approved
Bill of Sale (docClassification: 'bill-of-sale') ✅ ✅ ✅ ✅ Always generated; both parties sign
Power of Attorney (docClassification: 'poa') — ✅ ✅ ✅ Generated when a dealer is on either side
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
Self-inspection photos optional optional — — Requested by the buyer; not signed, and no event
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

GET /v2/deals/{dealId}/documents returns all of these in one list, with fresh 4-hour links — you do not need to know where each is kept. PrivateAuto does not generate a purchase agreement separate from the Bill of Sale (which serves as one), a financing addendum, or dealer "we-owe" forms.

Routing

Your account's routing setting, webhookScope, decides which records' events reach you. PrivateAuto sets it; the default is both.

webhookScope Listings Offers and deals Documents
appSource Listings started through your integration Offers and deals started through your integration Those on a deal that matches
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
both (default) Either Either Either

dealer.* events reach you for your own links only, whatever the setting.

If you are not receiving an event you expect, check in this order: that routing covers the record, that the endpoint's subscriptions include the event, and that the endpoint is active.

Building for change

  1. Process events by name, not by order. Several can arrive together (offer.accepted and deal.created, for example); treat their order as informational.
  2. Dedupe on eventId. A retried delivery carries the same one.
  3. Read the full record from the v2 reads when you need more than the payload carries.
  4. Move off the deprecated document events before 1 February 2027. Subscribe to document.* and branch on docClassification. Until then you receive both, so moving early costs nothing.
  5. Treat a missing event as possibly legitimate. The catalog says what can fire, not what must: some deals skip offer.accepted, and a deal can be marked sold without a separate listing event.

Deprecations

Deprecated surfaces keep working until their removal date. Nothing is removed without a date published here first, and dates only ever move outward.

Surface Kind Replacement Removal on or after
deal.poa_approved Event document.completed where docClassification === 'poa' 1 February 2027
deal.bill_of_sale_approved Event document.completed where docClassification === 'bill-of-sale' 1 February 2027

Both legacy events fire in addition to their replacements today, so you can migrate at any point before the removal date and simply ignore the duplicates in the meantime. After removal, only the document.* events fire.

Migrating: subscribe to document.signature_added and document.completed (or the document.* wildcard), then branch on docClassification instead of on the event name. The replacement events are strictly richer — they fire per document rather than per classification, carry the signers[] array, and cover document types the legacy pair never had an event for.

Renamed and merged events

Some event names in the Event Types catalog above have a canonical replacement. The deprecated names are not being removed and have no removal date: they stay subscribable and keep firing with the payload they have today. Wildcard subscriptions keep receiving the deprecated names for now and move to the canonical names at a cut-over date we will announce here (see below).

Deprecated event Canonical event source on the canonical event
deal.offer_accepted deal.terms_confirmed —
deal.title_approved deal.title_uploaded —
offer.cancelled offer.withdrawn —
offer.rejected offer.declined —
deal.negative_equity_identified deal.negative_equity_flagged service
deal.negative_equity_reported deal.negative_equity_flagged user
listing.ownership_set listing.ownership_updated service
listing.ownership_submitted listing.ownership_updated user

The canonical event fires at exactly the moment its deprecated counterpart does and carries the same payload. Where two deprecated events merged into one canonical event, it adds a source field naming the path that fired it: user for the user-side flow, service for the admin or service path.

When each canonical event fires (the trigger is its deprecated counterpart's, unchanged):

Canonical event When it fires
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
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
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
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)
offer.withdrawn The buyer withdraws an offer. Fires where offer.cancelled does
offer.declined The seller declines an offer. Fires where offer.rejected does

The Event sequences and Negative equity sections above use the deprecated names. Advice to subscribe to both deal.negative_equity_identified and deal.negative_equity_reported (or both listing.ownership_set and listing.ownership_submitted) applies only to an endpoint that receives the deprecated names (see the next table). An endpoint that receives deal.negative_equity_flagged or listing.ownership_updated gets one event per occurrence and reads source to tell the two paths apart.

Which name an endpoint receives depends on what it subscribes to. Each endpoint receives each event once:

Endpoint subscribes to Receives
The deprecated name only The deprecated name, payload unchanged
The canonical name The canonical name
A wildcard that covers it (deal.*, offer.*, listing.*, *), and not the canonical name The deprecated name, payload unchanged, until the announced cut-over
The canonical name, alone, beside the deprecated name or beside a wildcard The canonical name, once

The X-PA-Event header, the eventKey (and so the eventId derived from it) and the delivery log (GET /v2/webhooks/deliveries) all carry the name actually delivered, with two exceptions. Both are written once per partner rather than per endpoint, so no endpoint's subscription chooses their name, and both record the deprecated name:

  • a dlq row written because the event itself could not be processed after repeated attempts;
  • a skipped row with the error no webhook destinations resolved, written when you had no usable destination at all (for example, your only endpoint was disabled after repeated failures and no onboarding endpoint is configured).

If you filter the delivery log by event=<canonical name>, also query the deprecated name to see those rows.

GET /v2/webhooks/catalog lists the deprecated names under deprecated, each with its replacement.

Wildcard subscribers: nothing changes yet. An endpoint subscribed to deal.*, offer.*, listing.* or * keeps receiving the deprecated names. Wildcard subscriptions move to the canonical names at a cut-over date we will announce here. To switch earlier, add the canonical names to the endpoint's subscriptions beside the wildcard: from then on it receives those events under the canonical name, once. To stay on the deprecated names after the cut-over, subscribe to them explicitly.

The endpoint configured during onboarding, rather than through /v2/webhooks/endpoints, is unaffected: it keeps receiving the deprecated names, whatever it subscribes to.

Availability by release

This reference is a superset: it documents the v2 contract, and any given environment serves some prefix of it. Everything it documents that your environment has, it documents correctly — but an endpoint appearing here is not a promise that the environment you are pointed at serves it yet.

That gap is real rather than theoretical. The documentation site is built once and promoted, so it can describe a build newer than the service in front of you. As of this writing the webhook management endpoints (/v2/webhooks/endpoints, /subscriptions, /catalog) are present in some environments and absent in others, while the v2 read endpoints are more widely deployed.

Check what you are actually running, rather than inferring it from this page:

Question Ask
Does this environment serve v2 at all? GET /v2/me — 404 means no
Which webhook events may I subscribe to? GET /v2/webhooks/catalog — 404 means management is not deployed here
What is the live contract? GET /api/docs-json — the spec this environment is actually serving

A missing v2 route returns 404, and an existing one you are not authenticated for returns 401. That difference is the cheapest way to tell "not deployed" from "not authorised", and it is worth using before opening a support ticket.

Where webhook management is not yet available, your v1 configuration still applies: events continue to be delivered to the endpoint configured for your account, under the same delivery format and signature scheme. Nothing is lost by an environment being behind — only self-service is.

leads

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.

Submit a lead

Submit a lead for a dealership your partner account is associated with.

The 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.

Authorizations:
bearer
Request Body schema: application/json
required
callerReferenceId
required
string

Your own reference ID for this lead — used for idempotent dedup. Resubmitting the same value returns 409 with the existing lead ID.

organizationId
required
string

Target dealer organization ID. Must be on your partner allowlist.

leadCode
string

Lead code tag for categorization (e.g. CONQUEST, SERVICE, TRADE_IN)

object

The person selling the car

object

The car the seller wants to sell to the dealership

listingId
string

Link to an existing PrivateAuto listing ID

Responses

Request samples

Content type
application/json
{
  • "callerReferenceId": "LDR-98234",
  • "organizationId": "663a1f2b4e8c9a001234abcd",
  • "leadCode": "CONQUEST",
  • "contact": {
    },
  • "vehicle": {
    },
  • "listingId": "663b2f3c5e9d0b002345bcde"
}

Response samples

Content type
application/json
{
  • "leadId": "663c3f4d6fae0c003456cdef",
  • "callerReferenceId": "LDR-98234",
  • "status": "new",
  • "createdAt": "2026-04-16T14:22:00.000Z"
}

Look up a lead by callerReferenceId

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.

Requires 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.

Authorizations:
bearer
query Parameters
callerReferenceId
required
string non-empty

Your reference id for the lead

Responses

Response samples

Content type
application/json
{
  • "leadId": "663c3f4d6fae0c003456cdef",
  • "callerReferenceId": "LDR-98234",
  • "status": "new",
  • "organizationId": "663a1f4d6fae0c003456abcd",
  • "createdAt": "2026-04-16T14:22:00.000Z"
}

deals

Deals your organization is party to — read the deal, act on it, and track its documents

List deals your organization is party to

Authorizations:
bearer
query Parameters
_page
number
Default: 0

Zero-based page index

_limit
number
Default: 50

Page size (max 100)

status
string

Filter by status

callerReferenceId
string
Example: callerReferenceId=INV-20261103-0042

Only the offers or deals started from the invitation you sent with this callerReferenceId. A reference you never sent returns an empty page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "_meta": {
    }
}

Get one deal

Authorizations:
bearer
path Parameters
dealId
required
string

Deal id

Responses

Response samples

Content type
application/json
{
  • "id": "6a0243d9a30d4d0026d00e7c",
  • "guid": "653a905c-73b2-4e4b-bdf6-0e25b1e71363",
  • "status": "active",
  • "closingStatus": "none",
  • "closingFeePayer": "buyer",
  • "state": "UT",
  • "odometer": "string",
  • "appSource": "string",
  • "listingId": "string",
  • "offerId": "string",
  • "currentOfferStatus": "pending",
  • "documentsStatus": "empty",
  • "dealStateCurrent": true,
  • "negativeEquity": true,
  • "negativeEquityFunded": true,
  • "amount": 0,
  • "currency": "USD",
  • "buyer": {
    },
  • "seller": {
    },
  • "payment": {
    },
  • "documents": [
    ],
  • "dealState": {
    },
  • "titleApprovedAt": "2019-08-24T14:15:22Z",
  • "ownershipType": "owned",
  • "payoffType": "LOAN",
  • "loanPayoffDocs": [
    ],
  • "loanPayoffConfirmed": true,
  • "statusHistory": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "callerReferenceId": "INV-20261103-0042",
  • "price": 18500
}

Confirm the title as your side

Authorizations:
bearer
path Parameters
dealId
required
string

Deal id

Responses

Response samples

Content type
application/json
{
  • "dealId": "string",
  • "party": "buyer",
  • "message": "Successfully confirmed title."
}

Set service preferences on the deal

Authorizations:
bearer
path Parameters
dealId
required
string

Deal id

Request Body schema: application/json
required
object (PartyServicePreferencesDto)
object (PartyServicePreferencesDto)

Responses

Request samples

Content type
application/json
{
  • "buyer": {
    },
  • "seller": {
    }
}

Response samples

Content type
application/json
{
  • "dealId": "string",
  • "success": true
}

Cancel the deal

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.

Authorizations:
bearer
path Parameters
dealId
required
string

Deal id

Responses

Response samples

Content type
application/json
{
  • "dealId": "string",
  • "status": "cancelled",
  • "offerId": "string"
}

offers

Offers on a deal — read them, and counter, accept, decline or withdraw

List offers your organization is party to

Authorizations:
bearer
query Parameters
_page
number
Default: 0

Zero-based page index

_limit
number
Default: 50

Page size (max 100)

status
string

Filter by status

callerReferenceId
string
Example: callerReferenceId=INV-20261103-0042

Only the offers or deals started from the invitation you sent with this callerReferenceId. A reference you never sent returns an empty page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "_meta": {
    }
}

Send an offer

Sends an offer between a buyer and seller, and returns a deep link for each party. No deal exists until the counterparty accepts.

If 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.

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.

A 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.

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.

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).

Replaces POST /v2/deal-invites, which remains as a deprecated alias.

Acting for a linked dealership

If the buyer or seller email belongs to a user of a dealership your partner account is linked to, the deal is started for that dealership: that user is your side of the deal, and the offer and any new listing belong to their dealership. Otherwise your own organization is your side, as before.

A dealership becomes linked when POST /dealers/lookup/{partnerId} first returns it, or when the dealer group approves your OAuth client and that credential is first used. Both give the same standing, including to your own credentials, and it lasts until PrivateAuto revokes the link: withdrawing OAuth consent does not end it.

A deal can belong to only one dealership. If both emails match, or one email's user belongs to several linked dealerships, the request is rejected with 400 and a code — ambiguous_dealership_both_parties or ambiguous_dealership_multiple_orgs — whose message names the dealerships that collided. Nothing is created.

You can read these deals back: /data returns the offers and deals you started and their documents, with the listings you created or that belong to the dealership, even though they belong to the dealership's organization.

Webhooks for these offers, deals and new listings reach you only through appSource routing, so only with a webhookScope of appSource or both (the default). With organization you receive none of them: they carry the dealership's organization, not yours.

Authorizations:
bearer
Request Body schema: application/json
required
vin
required
string

Vehicle Identification Number (17 characters)

buyerName
string

Buyer full name

buyerEmail
string

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.

buyerSendLink
boolean

If true, emails the buyer their deal link (requires buyerEmail)

sellerName
string

Seller full name

sellerEmail
string

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.

sellerSendLink
boolean

If true, emails the seller their deal link (requires sellerEmail)

year
number

Vehicle model year. Required unless this VIN is already listed under your account.

make
string

Vehicle make. Required unless this VIN is already listed under your account.

model
string

Vehicle model. Required unless this VIN is already listed under your account.

trim
string

Vehicle trim level

amount
number
Deprecated

Deprecated: use price, which means the same thing. Offered price, in US dollars, not cents (18500 means $18,500).

expirationDate
string

Offer expiration as an ISO 8601 date/time. Must be in the future. Persisted to offer.expirationDate.

contingencies
Array of strings
Items Enum: "ai_self_inspection" "in_person_mechanical_inspection" "personal_inspection" "mechanic_inspection" "test_drive" "title_check"

Offer contingencies as an array of enum values. Each maps to a backing Offer boolean.

customConditions
Array of strings

Free-text contingency riders shown to the counterparty (max 10, 250 chars each)

customMessage
string

Message to the counterparty (max 1000 chars)

callerReferenceId
string

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.

partnerSide
string
Enum: "buyer" "seller"

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.

object

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.

dealerOrganizationId
string

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.

dealerExternalId
string

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.

price
number

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.

Responses

Request samples

Content type
application/json
{
  • "vin": "1HGBH41JXMN109186",
  • "buyerName": "Jane Smith",
  • "buyerEmail": "buyer@example.com",
  • "buyerSendLink": true,
  • "sellerName": "John Doe",
  • "sellerEmail": "seller@example.com",
  • "sellerSendLink": true,
  • "year": 2021,
  • "make": "Honda",
  • "model": "Civic",
  • "trim": "EX",
  • "amount": 18500,
  • "expirationDate": "2026-08-01T00:00:00.000Z",
  • "contingencies": [
    ],
  • "customConditions": [
    ],
  • "customMessage": "string",
  • "callerReferenceId": "INV-20261103-0042",
  • "partnerSide": "seller",
  • "counterparty": {
    },
  • "dealerOrganizationId": "663a1f2b4e8c9a001234abcd",
  • "dealerExternalId": "DLR-4471",
  • "price": 18500
}

Response samples

Content type
application/json
{
  • "offerId": "64a1f2e3b5c8d90012345678",
  • "dealId": "64a1f2e3b5c8d90012345679",
  • "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
  • "callerReferenceId": "INV-20261103-0042",
  • "buyerLink": "string",
  • "sellerLink": "string"
}

Get one offer

Authorizations:
bearer
path Parameters
offerId
required
string

Offer id

Responses

Response samples

Content type
application/json
{
  • "id": "6a0243d8a30d4d0026d00e7a",
  • "guid": "653a905c-73b2-4e4b-bdf6-0e25b1e71363",
  • "status": "pending",
  • "price": 0,
  • "currency": "USD",
  • "listingId": "string",
  • "offeredByUserId": "string",
  • "offeredByOrganizationId": "string",
  • "offeredToUserId": "string",
  • "offeredToOrganizationId": "string",
  • "externalId": "string",
  • "buyerExternalId": "string",
  • "sellerExternalId": "string",
  • "appSource": "string",
  • "dealNowExpiration": "2019-08-24T14:15:22Z",
  • "titleDeliveryMethod": "InPerson",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "callerReferenceId": "INV-20261103-0042"
}

Send an offer from an embedded widget (publishable key)

Browser-safe variant of POST /v2/offers for an embeddable make-offer widget.

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.

Rate limited to 10 requests per minute per client IP, counted across this path and its deprecated alias POST /v2/deal-invites/widget together.

Body 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.

Replaces POST /v2/deal-invites/widget, which remains as a deprecated alias.

header Parameters
x-pa-widget-key
required
string

Your widget publishable key (non-secret).

Request Body schema: application/json
required
vin
required
string

Vehicle Identification Number (17 characters)

buyerName
string

Buyer full name

buyerEmail
string

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.

buyerSendLink
boolean

If true, emails the buyer their deal link (requires buyerEmail)

sellerName
string

Seller full name

sellerEmail
string

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.

sellerSendLink
boolean

If true, emails the seller their deal link (requires sellerEmail)

year
number

Vehicle model year. Required unless this VIN is already listed under your account.

make
string

Vehicle make. Required unless this VIN is already listed under your account.

model
string

Vehicle model. Required unless this VIN is already listed under your account.

trim
string

Vehicle trim level

amount
number

Deal amount in dollars

expirationDate
string

Offer expiration as an ISO 8601 date/time. Must be in the future. Persisted to offer.expirationDate.

contingencies
Array of strings
Items Enum: "ai_self_inspection" "in_person_mechanical_inspection" "personal_inspection" "mechanic_inspection" "test_drive" "title_check"

Offer contingencies as an array of enum values. Each maps to a backing Offer boolean.

customConditions
Array of strings

Free-text contingency riders shown to the counterparty (max 10, 250 chars each)

customMessage
string

Message to the counterparty (max 1000 chars)

Responses

Request samples

Content type
application/json
{
  • "vin": "1HGBH41JXMN109186",
  • "buyerName": "Jane Smith",
  • "buyerEmail": "buyer@example.com",
  • "buyerSendLink": true,
  • "sellerName": "John Doe",
  • "sellerEmail": "seller@example.com",
  • "sellerSendLink": true,
  • "year": 2021,
  • "make": "Honda",
  • "model": "Civic",
  • "trim": "EX",
  • "amount": 18500,
  • "expirationDate": "2026-08-01T00:00:00.000Z",
  • "contingencies": [
    ],
  • "customConditions": [
    ],
  • "customMessage": "string"
}

Response samples

Content type
application/json
{
  • "offerId": "64a1f2e3b5c8d90012345678",
  • "dealId": "64a1f2e3b5c8d90012345679",
  • "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
  • "callerReferenceId": "INV-20261103-0042",
  • "buyerLink": "string",
  • "sellerLink": "string"
}

Counter the live offer on a deal

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.

Authorizations:
bearer
path Parameters
dealId
required
string

Deal id

Request Body schema: application/json
required
price
required
number

Your counter price, in US dollars, not cents (18500 means $18,500). Stored as sent, without rounding.

Responses

Request samples

Content type
application/json
{
  • "price": 24500
}

Accept the live offer, opening the deal

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.

Authorizations:
bearer
path Parameters
dealId
required
string

Deal id

Responses

Decline the live offer

Authorizations:
bearer
path Parameters
dealId
required
string

Deal id

Responses

Withdraw your own live offer

Authorizations:
bearer
path Parameters
dealId
required
string

Deal id

Responses

vehicles

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.

List vehicles your organization has listed

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.

Use 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.

Authorizations:
bearer
query Parameters
_page
number
Default: 0

Zero-based page index

_limit
number
Default: 50

Page size (max 100)

status
string

Filter by status

ownership
string
Enum: "listed" "purchased"

Limit to vehicles your organization listed for sale (listed) or bought through PrivateAuto (purchased).

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.

expand
Array of strings
Items Value: "deals"
Example: expand=deals

Optional joins. deals adds each vehicle’s completed sales and its latest DealNow id. Repeat the parameter or pass a comma-separated list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "_meta": {
    }
}

List a vehicle for sale

Creates a vehicle and its sale listing.

The listing is created as pending, exactly as one created through the app is — this endpoint does not publish it.

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.

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.

Authorizations:
bearer
Request Body schema: application/json
required
required
object

The vehicle being listed

price
required
number >= 0

Asking price in dollars

title
string

Listing title. Defaults to "{year} {make} {model}" when omitted.

zip
string

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.

Responses

Request samples

Content type
application/json
{
  • "vehicle": {
    },
  • "price": 18000,
  • "title": "2015 BMW 330i Sport — one owner",
  • "zip": "84043"
}

Response samples

Content type
application/json
{
  • "id": "6a024361a30d4d0026d00db2",
  • "vin": "WBA3B9C59FJ466190",
  • "year": 0,
  • "make": "string",
  • "model": "string",
  • "trim": "string",
  • "bodyStyle": "string",
  • "mileage": 0,
  • "exteriorColor": "string",
  • "interiorColor": "string",
  • "transmission": "string",
  • "driveType": "string",
  • "fuel": "string",
  • "cylinders": "string",
  • "condition": "new",
  • "ownershipInfo": {
    },
  • "listing": {
    },
  • "deals": [
    ],
  • "dealNowId": "string"
}

Get one vehicle

Authorizations:
bearer
path Parameters
vehicleId
required
string

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.

Responses

Response samples

Content type
application/json
{
  • "id": "6a024361a30d4d0026d00db2",
  • "vin": "WBA3B9C59FJ466190",
  • "year": 0,
  • "make": "string",
  • "model": "string",
  • "trim": "string",
  • "bodyStyle": "string",
  • "mileage": 0,
  • "exteriorColor": "string",
  • "interiorColor": "string",
  • "transmission": "string",
  • "driveType": "string",
  • "fuel": "string",
  • "cylinders": "string",
  • "condition": "new",
  • "ownershipInfo": {
    },
  • "listing": {
    },
  • "deals": [
    ],
  • "dealNowId": "string"
}

Change the asking price

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.

Authorizations:
bearer
path Parameters
vehicleId
required
string

Vehicle id

Request Body schema: application/json
required
price
required
number >= 0

New asking price in dollars

Responses

Request samples

Content type
application/json
{
  • "price": 17500
}

Response samples

Content type
application/json
{
  • "id": "6a024361a30d4d0026d00db2",
  • "vin": "WBA3B9C59FJ466190",
  • "year": 0,
  • "make": "string",
  • "model": "string",
  • "trim": "string",
  • "bodyStyle": "string",
  • "mileage": 0,
  • "exteriorColor": "string",
  • "interiorColor": "string",
  • "transmission": "string",
  • "driveType": "string",
  • "fuel": "string",
  • "cylinders": "string",
  • "condition": "new",
  • "ownershipInfo": {
    },
  • "listing": {
    },
  • "deals": [
    ],
  • "dealNowId": "string"
}

Take a vehicle off the market

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.

Authorizations:
bearer
path Parameters
vehicleId
required
string

Vehicle id

Responses

Response samples

Content type
application/json
{
  • "id": "6a024361a30d4d0026d00db2",
  • "vin": "WBA3B9C59FJ466190",
  • "year": 0,
  • "make": "string",
  • "model": "string",
  • "trim": "string",
  • "bodyStyle": "string",
  • "mileage": 0,
  • "exteriorColor": "string",
  • "interiorColor": "string",
  • "transmission": "string",
  • "driveType": "string",
  • "fuel": "string",
  • "cylinders": "string",
  • "condition": "new",
  • "ownershipInfo": {
    },
  • "listing": {
    },
  • "deals": [
    ],
  • "dealNowId": "string"
}

Publish a vehicle to the marketplace

Takes a pending listing live.

Requires vehicles:publish, which is not granted by default — ask PrivateAuto to enable it for your account.

Publishing 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.

Idempotent: publishing an already-live listing succeeds and does not restart its live window. A withdrawn listing must be reactivated first.

Authorizations:
bearer
path Parameters
vehicleId
required
string

Vehicle id

Responses

Response samples

Content type
application/json
{
  • "id": "6a024361a30d4d0026d00db2",
  • "vin": "WBA3B9C59FJ466190",
  • "year": 0,
  • "make": "string",
  • "model": "string",
  • "trim": "string",
  • "bodyStyle": "string",
  • "mileage": 0,
  • "exteriorColor": "string",
  • "interiorColor": "string",
  • "transmission": "string",
  • "driveType": "string",
  • "fuel": "string",
  • "cylinders": "string",
  • "condition": "new",
  • "ownershipInfo": {
    },
  • "listing": {
    },
  • "deals": [
    ],
  • "dealNowId": "string"
}

Put a withdrawn vehicle back on the market

The counterpart to deactivate. Returns the listing to pending; it does not publish, for the same reason creating does not.

Without 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.

Authorizations:
bearer
path Parameters
vehicleId
required
string

Vehicle id

Responses

Response samples

Content type
application/json
{
  • "id": "6a024361a30d4d0026d00db2",
  • "vin": "WBA3B9C59FJ466190",
  • "year": 0,
  • "make": "string",
  • "model": "string",
  • "trim": "string",
  • "bodyStyle": "string",
  • "mileage": 0,
  • "exteriorColor": "string",
  • "interiorColor": "string",
  • "transmission": "string",
  • "driveType": "string",
  • "fuel": "string",
  • "cylinders": "string",
  • "condition": "new",
  • "ownershipInfo": {
    },
  • "listing": {
    },
  • "deals": [
    ],
  • "dealNowId": "string"
}

List the photos on a vehicle, in display order

Authorizations:
bearer
path Parameters
vehicleId
required
string

Vehicle id

Responses

Response samples

Content type
application/json
{}

Add a photo to a vehicle

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.

Idempotent 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.

Authorizations:
bearer
path Parameters
vehicleId
required
string

Vehicle id

Request Body schema: multipart/form-data
required
file
required
string <binary>

JPEG, PNG or WebP image

Responses

Response samples

Content type
application/json
{}

Remove a photo from a vehicle

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.

Authorizations:
bearer
path Parameters
vehicleId
required
string

Vehicle id

photoId
required
string

Photo id, from the photos list

Responses

Response samples

Content type
application/json
{}

Set the display order of a vehicle’s photos

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.

Authorizations:
bearer
path Parameters
vehicleId
required
string

Vehicle id

Request Body schema: application/json
required
photoIds
required
Array of strings

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.

Responses

Request samples

Content type
application/json
{
  • "photoIds": [
    ]
}

Response samples

Content type
application/json
{}

documents

Documents attached to a deal — uploads, generated paperwork, and short-lived signed URLs to fetch them

All documents on a deal, with fresh signed URLs

Signed URLs are short-lived — each carries filename and expiresAt. Re-fetch rather than store.

Authorizations:
bearer
path Parameters
dealId
required
string

Responses

Response samples

Content type
application/json
{
  • "deal": {
    },
  • "title": [
    ],
  • "documents": [
    ]
}

Upload a document onto a deal

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.

Authorizations:
bearer
path Parameters
dealId
required
string

Deal id

Request Body schema: multipart/form-data
required
file
required
string <binary>

The document file (multipart field file)

documentType
required
string
Enum: "signed_title" "lien_release" "payoff_letter" "power_of_attorney" "disclosure" "other"

Document classification

callerReferenceId
required
string

Your own identifier for this upload — unique across ALL your uploads (namespace it, e.g. embed your deal/order id). Enables idempotent retry.

description
string

Free-text label surfaced in the deal UI and read endpoints

Responses

Response samples

Content type
application/json
{
  • "documentId": "string",
  • "duplicate": true,
  • "dealId": "string",
  • "documentType": "signed_title",
  • "callerReferenceId": "string",
  • "uploadedVia": "string",
  • "status": "string",
  • "contentType": "string",
  • "sizeBytes": 0,
  • "sha256": "string",
  • "url": "string",
  • "urlExpiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z"
}

One uploaded document, with a fresh signed URL

Authorizations:
bearer
path Parameters
documentId
required
string

Document id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "dealId": "string",
  • "docClassification": "string",
  • "status": "string",
  • "signers": [
    ],
  • "signed": [
    ]
}

Soft-void a document you uploaded

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).

Authorizations:
bearer
path Parameters
documentId
required
string

Document id

Responses

One PrivateAuto-generated document, with a fresh signed URL

Authorizations:
bearer
path Parameters
documentId
required
string

Document id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "docClassification": "string",
  • "name": "string",
  • "signers": [
    ],
  • "signed": [
    ]
}

webhooks

Self-service webhook delivery — register endpoints, choose the events each receives, rotate secrets, and inspect delivery attempts

List webhook delivery attempts

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.

Authorizations:
bearer
query Parameters
_page
number
Default: 0

Zero-based page index

_limit
number
Default: 50

Page size (max 100)

event
string

Filter by event name (e.g. deal.created)

dateFrom
string

ISO 8601 — only deliveries attempted at or after this time

dateTo
string

ISO 8601 — only deliveries attempted at or before this time

status
string
Enum: "delivered" "failed" "skipped" "dlq"

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.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "_meta": {
    }
}

Get one webhook delivery attempt

Authorizations:
bearer
path Parameters
logId
required
string

Delivery log id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "partnerId": "string",
  • "event": "deal.created",
  • "url": "string",
  • "statusCode": 0,
  • "attemptedAt": "2019-08-24T14:15:22Z",
  • "responseBodyExcerpt": "string",
  • "payload": { },
  • "status": "delivered",
  • "error": "string"
}

List your webhook endpoints

Authorizations:
bearer

Responses

Register a webhook endpoint

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.

Authorizations:
bearer
Request Body schema: application/json
required
url
required
string

HTTPS destination. Must resolve to a public address.

description
string

Your own label for this endpoint. Never used for routing.

subscriptions
Array of strings <= 100 items [ items <= 100 characters ]

Events to deliver here. Wildcards (deal.*, *) are accepted. An empty list means the endpoint receives nothing — it is inert, not a wildcard.

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "description": "string",
  • "subscriptions": [
    ]
}

Get one webhook endpoint

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Responses

Update a webhook endpoint

Changing the url returns the endpoint to unverified — a different destination needs its own proof.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Request Body schema: application/json
required
url
string

Changing this returns the endpoint to unverified.

description
string

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "description": "string"
}

Remove a webhook endpoint

Stops delivery. Delivery history is retained and stays readable via /webhooks/deliveries.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Responses

Complete the ownership challenge

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.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Responses

Response samples

Content type
application/json
{
  • "verified": true,
  • "status": 0,
  • "reason": "string"
}

Issue a new signing secret

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.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "secret": "string",
  • "previousSecretExpiresAt": "2019-08-24T14:15:22Z"
}

Deliver a synthetic event

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.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Responses

Response samples

Content type
application/json
{
  • "delivered": true,
  • "status": 0,
  • "signed": true,
  • "error": "string"
}

Events THIS credential may subscribe to

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.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "wildcards": [
    ],
  • "totalWildcardAvailable": true,
  • "notEntitled": [
    ],
  • "deprecated": [
    ]
}

Replace the whole subscription set

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.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Request Body schema: application/json
required
events
required
Array of strings <= 100 items [ items <= 100 characters ]

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.

Responses

Request samples

Content type
application/json
{
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "description": "string",
  • "state": "unverified",
  • "subscriptions": [
    ],
  • "verifiedAt": "2019-08-24T14:15:22Z",
  • "consecutiveFailures": 0,
  • "disabledAt": "2019-08-24T14:15:22Z",
  • "disabledReason": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Add to the subscription set

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Request Body schema: application/json
required
events
required
Array of strings <= 100 items [ items <= 100 characters ]

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.

Responses

Request samples

Content type
application/json
{
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "description": "string",
  • "state": "unverified",
  • "subscriptions": [
    ],
  • "verifiedAt": "2019-08-24T14:15:22Z",
  • "consecutiveFailures": 0,
  • "disabledAt": "2019-08-24T14:15:22Z",
  • "disabledReason": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Clear every subscription

The endpoint stays registered and verified, and receives nothing until you subscribe again.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "description": "string",
  • "state": "unverified",
  • "subscriptions": [
    ],
  • "verifiedAt": "2019-08-24T14:15:22Z",
  • "consecutiveFailures": 0,
  • "disabledAt": "2019-08-24T14:15:22Z",
  • "disabledReason": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Remove one subscription

Removing something you are not subscribed to is not an error — the end state is what you asked for.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

event
required
string

Event name or wildcard pattern

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "description": "string",
  • "state": "unverified",
  • "subscriptions": [
    ],
  • "verifiedAt": "2019-08-24T14:15:22Z",
  • "consecutiveFailures": 0,
  • "disabledAt": "2019-08-24T14:15:22Z",
  • "disabledReason": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Return a disabled endpoint to service

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.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "description": "string",
  • "state": "unverified",
  • "subscriptions": [
    ],
  • "verifiedAt": "2019-08-24T14:15:22Z",
  • "consecutiveFailures": 0,
  • "disabledAt": "2019-08-24T14:15:22Z",
  • "disabledReason": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Pause delivery without deleting the endpoint

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.

Authorizations:
bearer
path Parameters
endpointId
required
string

Webhook endpoint id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "description": "string",
  • "state": "unverified",
  • "subscriptions": [
    ],
  • "verifiedAt": "2019-08-24T14:15:22Z",
  • "consecutiveFailures": 0,
  • "disabledAt": "2019-08-24T14:15:22Z",
  • "disabledReason": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

dealers

Dealer organizations on your partner allowlist

List the dealerships you have linked

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.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Resolve one of your dealer ids to a PrivateAuto dealership

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.

Authorizations:
bearer
path Parameters
externalId
required
string

Your identifier for the dealership

Responses

Response samples

Content type
application/json
{
  • "organizationId": "string",
  • "name": "string",
  • "externalIds": [
    ]
}

deal-invites

DealNow deal initiation — invite a prospect into a PrivateAuto deal

Start a transaction and get per-party deep links Deprecated

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".

Authorizations:
bearer
Request Body schema: application/json
required
vin
required
string

Vehicle Identification Number (17 characters)

buyerName
string

Buyer full name

buyerEmail
string

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.

buyerSendLink
boolean

If true, emails the buyer their deal link (requires buyerEmail)

sellerName
string

Seller full name

sellerEmail
string

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.

sellerSendLink
boolean

If true, emails the seller their deal link (requires sellerEmail)

year
number

Vehicle model year. Required unless this VIN is already listed under your account.

make
string

Vehicle make. Required unless this VIN is already listed under your account.

model
string

Vehicle model. Required unless this VIN is already listed under your account.

trim
string

Vehicle trim level

amount
number
Deprecated

Deprecated: use price, which means the same thing. Offered price, in US dollars, not cents (18500 means $18,500).

expirationDate
string

Offer expiration as an ISO 8601 date/time. Must be in the future. Persisted to offer.expirationDate.

contingencies
Array of strings
Items Enum: "ai_self_inspection" "in_person_mechanical_inspection" "personal_inspection" "mechanic_inspection" "test_drive" "title_check"

Offer contingencies as an array of enum values. Each maps to a backing Offer boolean.

customConditions
Array of strings

Free-text contingency riders shown to the counterparty (max 10, 250 chars each)

customMessage
string

Message to the counterparty (max 1000 chars)

callerReferenceId
string

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.

partnerSide
string
Enum: "buyer" "seller"

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.

object

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.

dealerOrganizationId
string

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.

dealerExternalId
string

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.

price
number

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.

Responses

Request samples

Content type
application/json
{
  • "vin": "1HGBH41JXMN109186",
  • "buyerName": "Jane Smith",
  • "buyerEmail": "buyer@example.com",
  • "buyerSendLink": true,
  • "sellerName": "John Doe",
  • "sellerEmail": "seller@example.com",
  • "sellerSendLink": true,
  • "year": 2021,
  • "make": "Honda",
  • "model": "Civic",
  • "trim": "EX",
  • "amount": 18500,
  • "expirationDate": "2026-08-01T00:00:00.000Z",
  • "contingencies": [
    ],
  • "customConditions": [
    ],
  • "customMessage": "string",
  • "callerReferenceId": "INV-20261103-0042",
  • "partnerSide": "seller",
  • "counterparty": {
    },
  • "dealerOrganizationId": "663a1f2b4e8c9a001234abcd",
  • "dealerExternalId": "DLR-4471",
  • "price": 18500
}

Response samples

Content type
application/json
{
  • "offerId": "64a1f2e3b5c8d90012345678",
  • "dealId": "64a1f2e3b5c8d90012345679",
  • "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
  • "callerReferenceId": "INV-20261103-0042",
  • "buyerLink": "string",
  • "sellerLink": "string"
}

Start a transaction from an embedded widget (publishable key) Deprecated

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".

header Parameters
x-pa-widget-key
required
string

Your widget publishable key (non-secret).

Request Body schema: application/json
required
vin
required
string

Vehicle Identification Number (17 characters)

buyerName
string

Buyer full name

buyerEmail
string

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.

buyerSendLink
boolean

If true, emails the buyer their deal link (requires buyerEmail)

sellerName
string

Seller full name

sellerEmail
string

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.

sellerSendLink
boolean

If true, emails the seller their deal link (requires sellerEmail)

year
number

Vehicle model year. Required unless this VIN is already listed under your account.

make
string

Vehicle make. Required unless this VIN is already listed under your account.

model
string

Vehicle model. Required unless this VIN is already listed under your account.

trim
string

Vehicle trim level

amount
number

Deal amount in dollars

expirationDate
string

Offer expiration as an ISO 8601 date/time. Must be in the future. Persisted to offer.expirationDate.

contingencies
Array of strings
Items Enum: "ai_self_inspection" "in_person_mechanical_inspection" "personal_inspection" "mechanic_inspection" "test_drive" "title_check"

Offer contingencies as an array of enum values. Each maps to a backing Offer boolean.

customConditions
Array of strings

Free-text contingency riders shown to the counterparty (max 10, 250 chars each)

customMessage
string

Message to the counterparty (max 1000 chars)

Responses

Request samples

Content type
application/json
{
  • "vin": "1HGBH41JXMN109186",
  • "buyerName": "Jane Smith",
  • "buyerEmail": "buyer@example.com",
  • "buyerSendLink": true,
  • "sellerName": "John Doe",
  • "sellerEmail": "seller@example.com",
  • "sellerSendLink": true,
  • "year": 2021,
  • "make": "Honda",
  • "model": "Civic",
  • "trim": "EX",
  • "amount": 18500,
  • "expirationDate": "2026-08-01T00:00:00.000Z",
  • "contingencies": [
    ],
  • "customConditions": [
    ],
  • "customMessage": "string"
}

Response samples

Content type
application/json
{
  • "offerId": "64a1f2e3b5c8d90012345678",
  • "dealId": "64a1f2e3b5c8d90012345679",
  • "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
  • "callerReferenceId": "INV-20261103-0042",
  • "buyerLink": "string",
  • "sellerLink": "string"
}

me

Introspect the calling credential — who it is and which scopes it holds

Describe the calling credential

Returns the partner this credential authenticates as and the scopes it holds.

Call 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.

Unlike v1, the partner is derived from your token, not from the URL — there is no {partnerId} path segment in v2.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "partnerId": "acme",
  • "name": "Acme Motors",
  • "organizationId": "string",
  • "scopes": [
    ],
  • "apiVersion": "2.0.0"
}

reports

Dashboards PrivateAuto has shared with you, read with a credential or a report link

List the reports shared with you

Current shares only: none expired or revoked. A report link lists just its own report.

Authenticate 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.

Authorizations:
bearer
header Parameters
x-report-passcode
string

A report link's passcode, when it has one.

Responses

Response samples

Content type
application/json
{
  • "reports": [
    ]
}

Read one report

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.

Authenticate 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.

Authorizations:
bearer
path Parameters
shareId
required
string
header Parameters
x-report-passcode
string

A report link's passcode, when it has one.

Responses

Response samples

Content type
application/json
{
  • "shareId": "string",
  • "name": "string",
  • "mode": "live",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "version": 0,
  • "publishedAt": "2019-08-24T14:15:22Z",
  • "layout": [
    ],
  • "widgets": [
    ],
  • "filters": {
    }
}

wallets

Your organization's wallets and their transactions, as last reported by each wallet's provider

List your wallets

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.

Authorizations:
bearer
query Parameters
organizationId
string

Only wallets of this organization: your own, or one of your locations. Any other id returns an empty list.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get one wallet

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.

Authorizations:
bearer
path Parameters
walletId
required
string

Wallet id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization": {
    },
  • "provider": "checkbook",
  • "status": "verified",
  • "isPrimary": true,
  • "currency": "USD",
  • "balance": {
    },
  • "balanceAsOf": "2019-08-24T14:15:22Z",
  • "balanceProviderAsOf": "2019-08-24T14:15:22Z"
}

List a wallet's transactions

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.

Authorizations:
bearer
path Parameters
walletId
required
string

Wallet id

query Parameters
_page
number
Default: 0

Zero-based page index

_limit
number
Default: 50

Page size (max 100)

status
string
Enum: "pending" "completed" "failed" "cancelled"
type
string

Transaction type, e.g. transfer

direction
string
Enum: "in" "out"
from
string <date-time>

Created at or after this time

to
string <date-time>

Created before this time

dealId
string

Only transactions of this deal

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "_meta": {
    }
}

Get one wallet transaction

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.

Authorizations:
bearer
path Parameters
walletId
required
string

Wallet id

transactionId
required
string

Transaction id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "walletId": "string",
  • "type": "transfer",
  • "status": "pending",
  • "direction": "in",
  • "amount": 250000,
  • "currency": "USD",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "eta": "2019-08-24T14:15:22Z",
  • "network": "string",
  • "dealId": "string",
  • "counterparty": {
    }
}

marketplace

Search vehicles for sale on the marketplace

Searches every vehicle publicly listed for sale, not just your own — the only v2 read that is not scoped to your organization.

The 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.

Requires marketplace:search, which is not granted by default — ask PrivateAuto to enable it for your account.

Searches 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.

Free 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.

Authorizations:
bearer
query Parameters
marketplace
string
Default: "privateauto"
Enum: "privateauto" "dealnow"

Which marketplace to search. Omit it and you get privateauto, the platform default.

The 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.

More marketplaces are planned, so read the marketplaces field on each result rather than assuming everything came from the one you searched.

q
string
Example: q=bmw 330i sport

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.

make
string
Example: make=BMW

Manufacturer

model
string
Example: model=330i

Model name

yearMin
number
Example: yearMin=2015

Earliest model year

yearMax
number
Example: yearMax=2020

Latest model year

priceMin
number
Example: priceMin=5000

Minimum asking price in dollars

priceMax
number
Example: priceMax=30000

Maximum asking price in dollars

mileageMax
number
Example: mileageMax=80000

Maximum odometer reading

bodyStyle
string
Example: bodyStyle=sedan

Body style

fuel
string
Example: fuel=gasoline

Fuel type

transmission
string
Example: transmission=automatic

Transmission type

driveType
string
Example: driveType=AWD

Drive type

vehicleType
string
Enum: "Auto" "ATV/OHV" "Motorcycle" "RV" "Boat"

Vehicle category

sort
string
Default: "newest"
Enum: "newest" "price_asc" "price_desc" "mileage_asc"

Relevance ordering is not offered yet.

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.

_page
number
Default: 0

Zero-based page index

_limit
number
Default: 50

Page size (max 100)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "_meta": {
    }
}