Download OpenAPI specification:
Beta. Not all endpoints are fully tested and verified; use caution with production deployments.
build 2026.1119.5730-f196d97817
Partner integration API for DealNow initiation, lead ingestion, partner-scoped read access, and real-time webhook notifications.
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:
lead.* webhooks. You
can see a lead's status change, but not which offer or deal it became."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.
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.
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.
leads:write (default).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).organizationId is refused with 403; a location's credential cannot submit for its
parent or another location.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.
deal-invites:write (default);
deals:read and documents:read (default) to read the deal afterwards.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.deal.created, or poll GET /v2/deals?callerReferenceId=….GET /v2/deals/{dealId} and GET /v2/deals/{dealId}/documents as the deal progresses.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.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.deal-invites:write, deals:read,
documents:read, documents:write (default); deals:write (granted) to confirm title or cancel from
your system.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.GET /v2/deals?callerReferenceId=… to find the deal once the customer accepts.POST /v2/deals/{dealId}/documents to attach your paperwork; GET /v2/deals/{dealId}/documents
to collect signed copies.deals:write: POST /v2/deals/{dealId}/title/confirm, POST /v2/deals/{dealId}/cancel.deal.* and document.*; add offer.* to see declines and withdrawals before a deal
exists.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).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.POST /v2/offers.marketplace:search (granted).GET /v2/marketplace/vehicles to search every vehicle publicly listed for sale.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.deal-invites:write (default).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.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.deals:read and vehicles:read, and reads the dealer's organization and its
locations.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.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.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:
dealId being null. An offer is not a deal. Do not fetch /v2/deals/{dealId} with
an offerId — it returns 404.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 and a redirectUrl (the generic error
page in the user's app, safe to send them to). 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.
Get a Sandbox credential. Ask PrivateAuto for a Sandbox partner secret or organization API key. Build against the Sandbox first.
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.
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"}'
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.
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:
GET /v2/me.buyerEmail / sellerEmail. An offer
with counterparty.sendLink (or sellerSendLink / buyerSendLink) set can send a real email to the
address you give.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.
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.
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.
expis required in v2. v1 accepts a token without one, which is a bearer credential that never ages out. If your v1 signing code omitsexp, 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)
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:
GET /v2/me will show you an empty scopes array rather than failing.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.
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.
client_id, your registered
redirect_uri, response_type=code, a state value you generate, and a PKCE
code_challenge (with code_challenge_method=S256).redirect_uri with code and
your state. Check the state matches before going further.code_verifier that matches the challenge from step 1.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:
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.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.
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.
A dealer can withdraw consent at any time. When they do:
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.
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.
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).
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:
deals:read and vehicles:read, intersected with your
account's scopes.POST /v2/offers/widget, which checks your account
holds deal-invites:write.Abbreviated: each endpoint's reference below lists every field.
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",
"redirectUrl": "https://app.privateauto.com/error"
}
redirectUrl is the generic error page in the user's PrivateAuto or DealNow app (matching your link
platform). It is public and carries no token, so you can send the user there instead of showing the error.
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" } }.
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" }
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"
}
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 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, and redirectUrl, the generic error page in the user's PrivateAuto or DealNow app, safe to send them to), POST /v2/leads (carries leadId; any reuse) or a document upload (a different file) |
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 |
| 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.
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.
| 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:
POST /v2/webhooks/endpoints with your URL. It starts unverified, and only active endpoints
receive events.POST .../test to confirm it accepts a delivery and your signature check passes.POST .../verify to prove you control the URL. The endpoint becomes active.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.
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.
previousSecretExpiresAt, then remove it.GET /v2/webhooks/deliveries?status=dlq for you to reconcile.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.
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.
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:
GET /v2/webhooks/deliveries after cutover; a silent return to the old
destination looks a lot like nothing having happened.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.
Every delivery includes an X-PA-Signature header of the form sha256={hex}. To verify:
X-PA-Timestamp from the request headers.{timestamp}.{raw_body}.sha256= in X-PA-Signature.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.
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 — onlyeventIdis 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.
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.
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 |
| 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. FetchGET /v2/deals/{dealId}for the deal'slistingId, thenGET /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.
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) |
| 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 |
| 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 |
| 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 |
2xx status to acknowledge receipt.2xx immediately and process the event asynchronously if your handler is slow.401 for signature failures so PrivateAuto can flag delivery issues.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.
Which events arrive, and in what order, depends on which side you are on and how the deal started.
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 |
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.
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 }
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
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.
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).
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.
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.
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
| 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.
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.
offer.accepted and
deal.created, for example); treat their order as informational.eventId. A retried delivery carries the same one.document.* and
branch on docClassification. Until then you receive both, so moving early costs nothing.offer.accepted, and a deal can be marked sold without a separate listing event.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.
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:
dlq row written because the event itself could not be processed after repeated attempts;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.
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.
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 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.
| 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 |
{- "callerReferenceId": "LDR-98234",
- "organizationId": "663a1f2b4e8c9a001234abcd",
- "leadCode": "CONQUEST",
- "contact": {
- "name": "Jane Smith",
- "email": "jane@example.com",
- "phone": "555-867-5309",
- "message": "Looking to sell my 2019 Accord. One owner, clean title."
}, - "vehicle": {
- "vin": "1HGBH41JXMN109186",
- "year": 2019,
- "make": "Honda",
- "model": "Accord",
- "trim": "Sport",
- "mileage": 42000
}, - "listingId": "663b2f3c5e9d0b002345bcde"
}{- "leadId": "663c3f4d6fae0c003456cdef",
- "callerReferenceId": "LDR-98234",
- "status": "new",
- "createdAt": "2026-04-16T14:22:00.000Z"
}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.
| callerReferenceId required | string non-empty Your reference id for the lead |
{- "leadId": "663c3f4d6fae0c003456cdef",
- "callerReferenceId": "LDR-98234",
- "status": "new",
- "organizationId": "663a1f4d6fae0c003456abcd",
- "createdAt": "2026-04-16T14:22:00.000Z"
}| _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 |
{- "data": [
- {
- "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": {
- "id": "6a0243d9a30d4d0026d00e7c",
- "organizationId": "67e446a09d2eb254a3b130e7",
- "status": "invited",
- "titleConfirmedDate": "2019-08-24T14:15:22Z",
- "confirmedDate": "2019-08-24T14:15:22Z",
- "infoCompletedAt": "2019-08-24T14:15:22Z",
- "termsConfirmedAt": "2019-08-24T14:15:22Z",
- "paymentConfirmedAt": "2019-08-24T14:15:22Z",
- "titleConfirmedAt": "2019-08-24T14:15:22Z",
- "servicesConfirmedAt": "2019-08-24T14:15:22Z",
- "titleSubmittedAt": "2019-08-24T14:15:22Z"
}, - "seller": {
- "id": "6a0243d9a30d4d0026d00e7c",
- "organizationId": "67e446a09d2eb254a3b130e7",
- "status": "invited",
- "titleConfirmedDate": "2019-08-24T14:15:22Z",
- "confirmedDate": "2019-08-24T14:15:22Z",
- "infoCompletedAt": "2019-08-24T14:15:22Z",
- "termsConfirmedAt": "2019-08-24T14:15:22Z",
- "paymentConfirmedAt": "2019-08-24T14:15:22Z",
- "titleConfirmedAt": "2019-08-24T14:15:22Z",
- "servicesConfirmedAt": "2019-08-24T14:15:22Z",
- "titleSubmittedAt": "2019-08-24T14:15:22Z"
}, - "payment": {
- "privateAutoPay": {
- "amount": 0,
- "transferDate": "2019-08-24T14:15:22Z",
- "checkDelivery": "pickup",
- "payoutSourceType": "wallet"
}, - "cash": {
- "amount": 0,
- "transferDate": "2019-08-24T14:15:22Z"
}, - "loan": {
- "amount": 0,
- "transferDate": "2019-08-24T14:15:22Z"
}, - "crypto": {
- "btc": {
- "amount": 0,
- "transferDate": "2019-08-24T14:15:22Z"
}
}
}, - "documents": [
- {
- "id": "string",
- "status": "string",
- "docClassification": "string"
}
], - "dealState": {
- "documentsStatus": "empty"
}, - "titleApprovedAt": "2019-08-24T14:15:22Z",
- "ownershipType": "owned",
- "payoffType": "LOAN",
- "loanPayoffDocs": [
- {
- "fileUrl": "string",
- "filename": "string",
- "expiresAt": "2019-08-24T14:15:22Z"
}
], - "loanPayoffConfirmed": true,
- "statusHistory": [
- {
- "value": "string",
- "previous": "string",
- "date": "2019-08-24T14:15:22Z"
}
], - "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "callerReferenceId": "INV-20261103-0042",
- "price": 18500
}
], - "_meta": {
- "page": 0,
- "limit": 50,
- "total": 137,
- "hasMore": true
}
}{- "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": {
- "id": "6a0243d9a30d4d0026d00e7c",
- "organizationId": "67e446a09d2eb254a3b130e7",
- "status": "invited",
- "titleConfirmedDate": "2019-08-24T14:15:22Z",
- "confirmedDate": "2019-08-24T14:15:22Z",
- "infoCompletedAt": "2019-08-24T14:15:22Z",
- "termsConfirmedAt": "2019-08-24T14:15:22Z",
- "paymentConfirmedAt": "2019-08-24T14:15:22Z",
- "titleConfirmedAt": "2019-08-24T14:15:22Z",
- "servicesConfirmedAt": "2019-08-24T14:15:22Z",
- "titleSubmittedAt": "2019-08-24T14:15:22Z"
}, - "seller": {
- "id": "6a0243d9a30d4d0026d00e7c",
- "organizationId": "67e446a09d2eb254a3b130e7",
- "status": "invited",
- "titleConfirmedDate": "2019-08-24T14:15:22Z",
- "confirmedDate": "2019-08-24T14:15:22Z",
- "infoCompletedAt": "2019-08-24T14:15:22Z",
- "termsConfirmedAt": "2019-08-24T14:15:22Z",
- "paymentConfirmedAt": "2019-08-24T14:15:22Z",
- "titleConfirmedAt": "2019-08-24T14:15:22Z",
- "servicesConfirmedAt": "2019-08-24T14:15:22Z",
- "titleSubmittedAt": "2019-08-24T14:15:22Z"
}, - "payment": {
- "privateAutoPay": {
- "amount": 0,
- "transferDate": "2019-08-24T14:15:22Z",
- "checkDelivery": "pickup",
- "payoutSourceType": "wallet"
}, - "cash": {
- "amount": 0,
- "transferDate": "2019-08-24T14:15:22Z"
}, - "loan": {
- "amount": 0,
- "transferDate": "2019-08-24T14:15:22Z"
}, - "crypto": {
- "btc": {
- "amount": 0,
- "transferDate": "2019-08-24T14:15:22Z"
}
}
}, - "documents": [
- {
- "id": "string",
- "status": "string",
- "docClassification": "string"
}
], - "dealState": {
- "documentsStatus": "empty"
}, - "titleApprovedAt": "2019-08-24T14:15:22Z",
- "ownershipType": "owned",
- "payoffType": "LOAN",
- "loanPayoffDocs": [
- {
- "fileUrl": "string",
- "filename": "string",
- "expiresAt": "2019-08-24T14:15:22Z"
}
], - "loanPayoffConfirmed": true,
- "statusHistory": [
- {
- "value": "string",
- "previous": "string",
- "date": "2019-08-24T14:15:22Z"
}
], - "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "callerReferenceId": "INV-20261103-0042",
- "price": 18500
}| dealId required | string Deal id |
object (PartyServicePreferencesDto) | |
object (PartyServicePreferencesDto) |
{- "buyer": {
- "titlePurchaseShow": true
}, - "seller": {
- "titlePurchaseShow": true
}
}{- "dealId": "string",
- "success": true
}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.
| dealId required | string Deal id |
{- "dealId": "string",
- "status": "cancelled",
- "offerId": "string"
}| _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 |
{- "data": [
- {
- "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"
}
], - "_meta": {
- "page": 0,
- "limit": 50,
- "total": 137,
- "hasMore": true
}
}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 and a redirectUrl (the generic error page in the user's app, safe to send them to).
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.
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.
| vin required | string Vehicle Identification Number (17 characters) |
| buyerName | string Buyer full name |
| buyerEmail | string Buyer email address. Without |
| buyerSendLink | boolean If true, emails the buyer their deal link (requires buyerEmail) |
| sellerName | string Seller full name |
| sellerEmail | string Seller email address. Without |
| 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 |
| 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 |
| 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 |
object The other party, the one being invited. Requires | |
| dealerOrganizationId | string The PrivateAuto organization id of the dealership this deal is for. When sent (or |
| dealerExternalId | string Your own identifier for the dealership: the |
| 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 |
{- "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": [
- "ai_self_inspection",
- "test_drive"
], - "customConditions": [
- "Subject to clean title",
- "Pending finance approval"
], - "customMessage": "string",
- "callerReferenceId": "INV-20261103-0042",
- "partnerSide": "seller",
- "counterparty": {
- "email": "jane@example.com",
- "name": "Jane Smith",
- "sendLink": true
}, - "dealerOrganizationId": "663a1f2b4e8c9a001234abcd",
- "dealerExternalId": "DLR-4471",
- "price": 18500
}{- "offerId": "64a1f2e3b5c8d90012345678",
- "dealId": "64a1f2e3b5c8d90012345679",
- "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
- "callerReferenceId": "INV-20261103-0042",
- "buyerLink": "string",
- "sellerLink": "string"
}{- "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"
}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.
| x-pa-widget-key required | string Your widget publishable key (non-secret). |
| 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 |
| 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 |
| 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) |
{- "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": [
- "ai_self_inspection",
- "test_drive"
], - "customConditions": [
- "Subject to clean title",
- "Pending finance approval"
], - "customMessage": "string"
}{- "offerId": "64a1f2e3b5c8d90012345678",
- "dealId": "64a1f2e3b5c8d90012345679",
- "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
- "callerReferenceId": "INV-20261103-0042",
- "buyerLink": "string",
- "sellerLink": "string"
}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.
| dealId required | string Deal id |
| price required | number Your counter price, in US dollars, not cents (18500 means $18,500). Stored as sent, without rounding. |
{- "price": 24500
}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.
| dealId required | string Deal id |
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.
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.
| _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 ( These two do not add up to the whole collection. Omit the parameter to return every vehicle, including ones removed from sale — which |
| expand | Array of strings Items Value: "deals" Example: expand=deals Optional joins. |
{- "data": [
- {
- "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": {
- "ownershipType": "owned",
- "vehicleHaveLien": true
}, - "listing": {
- "listingNo": "string",
- "slug": "string",
- "title": "string",
- "status": "pending",
- "price": 0,
- "sellerId": "string",
- "organizationId": "string",
- "appSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}, - "deals": [
- {
- "id": "663c3f4d6fae0c003456cdef",
- "guid": "string"
}
], - "dealNowId": "string"
}
], - "_meta": {
- "page": 0,
- "limit": 50,
- "total": 137,
- "hasMore": true
}
}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.
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. |
{- "vehicle": {
- "year": 2015,
- "make": "BMW",
- "model": "330i",
- "trim": "Sport",
- "vin": "WBA3B9C59FJ466190",
- "mileage": 62000,
- "bodyStyle": "sedan",
- "exteriorColor": "Alpine White",
- "interiorColor": "Black",
- "transmission": "automatic",
- "driveType": "RWD",
- "fuel": "gasoline",
- "cylinders": "4",
- "vehicleType": "Auto",
- "condition": "new"
}, - "price": 18000,
- "title": "2015 BMW 330i Sport — one owner",
- "zip": "84043"
}{- "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": {
- "ownershipType": "owned",
- "vehicleHaveLien": true
}, - "listing": {
- "listingNo": "string",
- "slug": "string",
- "title": "string",
- "status": "pending",
- "price": 0,
- "sellerId": "string",
- "organizationId": "string",
- "appSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}, - "deals": [
- {
- "id": "663c3f4d6fae0c003456cdef",
- "guid": "string"
}
], - "dealNowId": "string"
}| vehicleId required | string Vehicle id — the |
{- "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": {
- "ownershipType": "owned",
- "vehicleHaveLien": true
}, - "listing": {
- "listingNo": "string",
- "slug": "string",
- "title": "string",
- "status": "pending",
- "price": 0,
- "sellerId": "string",
- "organizationId": "string",
- "appSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}, - "deals": [
- {
- "id": "663c3f4d6fae0c003456cdef",
- "guid": "string"
}
], - "dealNowId": "string"
}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.
| vehicleId required | string Vehicle id |
| price required | number >= 0 New asking price in dollars |
{- "price": 17500
}{- "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": {
- "ownershipType": "owned",
- "vehicleHaveLien": true
}, - "listing": {
- "listingNo": "string",
- "slug": "string",
- "title": "string",
- "status": "pending",
- "price": 0,
- "sellerId": "string",
- "organizationId": "string",
- "appSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}, - "deals": [
- {
- "id": "663c3f4d6fae0c003456cdef",
- "guid": "string"
}
], - "dealNowId": "string"
}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.
| vehicleId required | string Vehicle id |
{- "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": {
- "ownershipType": "owned",
- "vehicleHaveLien": true
}, - "listing": {
- "listingNo": "string",
- "slug": "string",
- "title": "string",
- "status": "pending",
- "price": 0,
- "sellerId": "string",
- "organizationId": "string",
- "appSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}, - "deals": [
- {
- "id": "663c3f4d6fae0c003456cdef",
- "guid": "string"
}
], - "dealNowId": "string"
}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.
| vehicleId required | string Vehicle id |
{- "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": {
- "ownershipType": "owned",
- "vehicleHaveLien": true
}, - "listing": {
- "listingNo": "string",
- "slug": "string",
- "title": "string",
- "status": "pending",
- "price": 0,
- "sellerId": "string",
- "organizationId": "string",
- "appSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}, - "deals": [
- {
- "id": "663c3f4d6fae0c003456cdef",
- "guid": "string"
}
], - "dealNowId": "string"
}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.
| vehicleId required | string Vehicle id |
{- "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": {
- "ownershipType": "owned",
- "vehicleHaveLien": true
}, - "listing": {
- "listingNo": "string",
- "slug": "string",
- "title": "string",
- "status": "pending",
- "price": 0,
- "sellerId": "string",
- "organizationId": "string",
- "appSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}, - "deals": [
- {
- "id": "663c3f4d6fae0c003456cdef",
- "guid": "string"
}
], - "dealNowId": "string"
}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.
| vehicleId required | string Vehicle id |
| file required | string <binary> JPEG, PNG or WebP image |
{- "vehicleId": "6a024361a30d4d0026d00db2",
- "photos": [
- {
- "id": "9f2c1e7a4b6d8e0f1a2b3c4d",
- "position": 0,
- "primary": true
}
]
}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.
| vehicleId required | string Vehicle id |
| photoId required | string Photo id, from the photos list |
{- "vehicleId": "6a024361a30d4d0026d00db2",
- "photos": [
- {
- "id": "9f2c1e7a4b6d8e0f1a2b3c4d",
- "position": 0,
- "primary": true
}
]
}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.
| vehicleId required | string Vehicle id |
| 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. |
{- "photoIds": [
- "string"
]
}{- "vehicleId": "6a024361a30d4d0026d00db2",
- "photos": [
- {
- "id": "9f2c1e7a4b6d8e0f1a2b3c4d",
- "position": 0,
- "primary": true
}
]
}Documents attached to a deal — uploads, generated paperwork, and short-lived signed URLs to fetch them
Signed URLs are short-lived — each carries filename and expiresAt. Re-fetch rather than store.
| dealId required | string |
{- "deal": {
- "id": "string",
- "guid": "string"
}, - "title": [
- {
- "key": "string",
- "url": "string",
- "expiresAt": "2019-08-24T14:15:22Z"
}
], - "documents": [
- {
- "id": "string",
- "docClassification": "string",
- "status": "string",
- "name": "string",
- "signers": [
- {
- "signerRole": "seller",
- "signedAt": "2019-08-24T14:15:22Z"
}
], - "signed": [
- {
- "key": "string",
- "url": "string",
- "expiresAt": "2019-08-24T14:15:22Z"
}
]
}
]
}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.
| dealId required | string Deal id |
| file required | string <binary> The document file (multipart field |
| 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 |
{- "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"
}| documentId required | string Document id |
{- "id": "string",
- "dealId": "string",
- "docClassification": "string",
- "status": "string",
- "signers": [
- {
- "signerRole": "seller",
- "signedAt": "2019-08-24T14:15:22Z"
}
], - "signed": [
- {
- "key": "string",
- "url": "string",
- "expiresAt": "2019-08-24T14:15:22Z"
}
]
}| documentId required | string Document id |
{- "id": "string",
- "docClassification": "string",
- "name": "string",
- "signers": [
- {
- "signerRole": "seller",
- "signedAt": "2019-08-24T14:15:22Z"
}
], - "signed": [
- {
- "key": "string",
- "url": "string",
- "expiresAt": "2019-08-24T14:15:22Z"
}
]
}Self-service webhook delivery — register endpoints, choose the events each receives, rotate secrets, and inspect 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.
| _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. |
{- "data": [
- {
- "id": "string",
- "partnerId": "string",
- "event": "deal.created",
- "url": "string",
- "statusCode": 0,
- "attemptedAt": "2019-08-24T14:15:22Z",
- "responseBodyExcerpt": "string",
- "payload": { },
- "status": "delivered",
- "error": "string"
}
], - "_meta": {
- "page": 0,
- "limit": 50,
- "total": 137,
- "hasMore": true
}
}| logId required | string Delivery log id |
{- "id": "string",
- "partnerId": "string",
- "event": "deal.created",
- "url": "string",
- "statusCode": 0,
- "attemptedAt": "2019-08-24T14:15:22Z",
- "responseBodyExcerpt": "string",
- "payload": { },
- "status": "delivered",
- "error": "string"
}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.
| 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 ( |
{- "url": "string",
- "description": "string",
- "subscriptions": [
- "string"
]
}Changing the url returns the endpoint to unverified — a different destination needs its own proof.
| endpointId required | string Webhook endpoint id |
| url | string Changing this returns the endpoint to |
| description | string |
{- "url": "string",
- "description": "string"
}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.
| endpointId required | string Webhook endpoint id |
{- "verified": true,
- "status": 0,
- "reason": "string"
}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.
| endpointId required | string Webhook endpoint id |
{- "id": "string",
- "secret": "string",
- "previousSecretExpiresAt": "2019-08-24T14:15:22Z"
}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.
| endpointId required | string Webhook endpoint id |
{- "delivered": true,
- "status": 0,
- "signed": true,
- "error": "string"
}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.
{- "events": [
- "string"
], - "wildcards": [
- "string"
], - "totalWildcardAvailable": true,
- "notEntitled": [
- {
- "namespace": "string",
- "requiredScope": "string"
}
], - "deprecated": [
- {
- "event": "string",
- "replacement": "string"
}
]
}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.
| endpointId required | string Webhook endpoint id |
| events required | Array of strings <= 100 items [ items <= 100 characters ] Event names or wildcard patterns. |
{- "events": [
- "string"
]
}{- "id": "string",
- "url": "string",
- "description": "string",
- "state": "unverified",
- "subscriptions": [
- "string"
], - "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"
}| endpointId required | string Webhook endpoint id |
| events required | Array of strings <= 100 items [ items <= 100 characters ] Event names or wildcard patterns. |
{- "events": [
- "string"
]
}{- "id": "string",
- "url": "string",
- "description": "string",
- "state": "unverified",
- "subscriptions": [
- "string"
], - "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"
}The endpoint stays registered and verified, and receives nothing until you subscribe again.
| endpointId required | string Webhook endpoint id |
{- "id": "string",
- "url": "string",
- "description": "string",
- "state": "unverified",
- "subscriptions": [
- "string"
], - "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"
}Removing something you are not subscribed to is not an error — the end state is what you asked for.
| endpointId required | string Webhook endpoint id |
| event required | string Event name or wildcard pattern |
{- "id": "string",
- "url": "string",
- "description": "string",
- "state": "unverified",
- "subscriptions": [
- "string"
], - "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"
}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.
| endpointId required | string Webhook endpoint id |
{- "id": "string",
- "url": "string",
- "description": "string",
- "state": "unverified",
- "subscriptions": [
- "string"
], - "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"
}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.
| endpointId required | string Webhook endpoint id |
{- "id": "string",
- "url": "string",
- "description": "string",
- "state": "unverified",
- "subscriptions": [
- "string"
], - "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"
}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.
[- {
- "organizationId": "string",
- "name": "string",
- "externalIds": [
- {
- "value": "D-1042",
- "label": "string",
- "linkedAt": "2019-08-24T14:15:22Z"
}
]
}
]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.
| externalId required | string Your identifier for the dealership |
{- "organizationId": "string",
- "name": "string",
- "externalIds": [
- {
- "value": "D-1042",
- "label": "string",
- "linkedAt": "2019-08-24T14:15:22Z"
}
]
}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".
| vin required | string Vehicle Identification Number (17 characters) |
| buyerName | string Buyer full name |
| buyerEmail | string Buyer email address. Without |
| buyerSendLink | boolean If true, emails the buyer their deal link (requires buyerEmail) |
| sellerName | string Seller full name |
| sellerEmail | string Seller email address. Without |
| 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 |
| 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 |
| 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 |
object The other party, the one being invited. Requires | |
| dealerOrganizationId | string The PrivateAuto organization id of the dealership this deal is for. When sent (or |
| dealerExternalId | string Your own identifier for the dealership: the |
| 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 |
{- "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": [
- "ai_self_inspection",
- "test_drive"
], - "customConditions": [
- "Subject to clean title",
- "Pending finance approval"
], - "customMessage": "string",
- "callerReferenceId": "INV-20261103-0042",
- "partnerSide": "seller",
- "counterparty": {
- "email": "jane@example.com",
- "name": "Jane Smith",
- "sendLink": true
}, - "dealerOrganizationId": "663a1f2b4e8c9a001234abcd",
- "dealerExternalId": "DLR-4471",
- "price": 18500
}{- "offerId": "64a1f2e3b5c8d90012345678",
- "dealId": "64a1f2e3b5c8d90012345679",
- "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
- "callerReferenceId": "INV-20261103-0042",
- "buyerLink": "string",
- "sellerLink": "string"
}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".
| x-pa-widget-key required | string Your widget publishable key (non-secret). |
| 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 |
| 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 |
| 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) |
{- "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": [
- "ai_self_inspection",
- "test_drive"
], - "customConditions": [
- "Subject to clean title",
- "Pending finance approval"
], - "customMessage": "string"
}{- "offerId": "64a1f2e3b5c8d90012345678",
- "dealId": "64a1f2e3b5c8d90012345679",
- "guid": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8",
- "callerReferenceId": "INV-20261103-0042",
- "buyerLink": "string",
- "sellerLink": "string"
}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.
{- "partnerId": "acme",
- "name": "Acme Motors",
- "organizationId": "string",
- "scopes": [
- "deals:read"
], - "apiVersion": "2.0.0"
}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.
| x-report-passcode | string A report link's passcode, when it has one. |
{- "reports": [
- {
- "shareId": "string",
- "name": "string",
- "mode": "live",
- "expiresAt": "2019-08-24T14:15:22Z"
}
]
}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.
| shareId required | string |
| x-report-passcode | string A report link's passcode, when it has one. |
{- "shareId": "string",
- "name": "string",
- "mode": "live",
- "expiresAt": "2019-08-24T14:15:22Z",
- "description": "string",
- "version": 0,
- "publishedAt": "2019-08-24T14:15:22Z",
- "layout": [
- {
- "i": "string",
- "x": 0,
- "y": 0,
- "w": 0,
- "h": 0
}
], - "widgets": [
- {
- "id": "string",
- "catalogKey": "string",
- "title": "string",
- "viz": "kpi",
- "dateRangeOverride": {
- "preset": "7d",
- "from": "string",
- "to": "string"
}, - "refreshSeconds": 0
}
], - "filters": {
- "dateRange": {
- "preset": "7d",
- "from": "string",
- "to": "string"
}
}
}Your organization's wallets and their transactions, as last reported by each wallet's provider
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.
| organizationId | string Only wallets of this organization: your own, or one of your locations. Any other id returns an empty list. |
[- {
- "id": "string",
- "organization": {
- "id": "string",
- "name": "string",
- "isLocation": true
}, - "provider": "checkbook",
- "status": "verified",
- "isPrimary": true,
- "currency": "USD",
- "balance": {
- "available": 1250000,
- "pendingIn": 0,
- "pendingOut": 250000
}, - "balanceAsOf": "2019-08-24T14:15:22Z",
- "balanceProviderAsOf": "2019-08-24T14:15:22Z"
}
]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.
| walletId required | string Wallet id |
{- "id": "string",
- "organization": {
- "id": "string",
- "name": "string",
- "isLocation": true
}, - "provider": "checkbook",
- "status": "verified",
- "isPrimary": true,
- "currency": "USD",
- "balance": {
- "available": 1250000,
- "pendingIn": 0,
- "pendingOut": 250000
}, - "balanceAsOf": "2019-08-24T14:15:22Z",
- "balanceProviderAsOf": "2019-08-24T14:15:22Z"
}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.
| walletId required | string Wallet id |
| _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. |
| 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 |
{- "data": [
- {
- "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": {
- "type": "bank"
}
}
], - "_meta": {
- "page": 0,
- "limit": 50,
- "total": 137,
- "hasMore": true
}
}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.
| walletId required | string Wallet id |
| transactionId required | string Transaction id |
{- "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": {
- "type": "bank"
}
}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.
| marketplace | string Default: "privateauto" Enum: "privateauto" "dealnow" Which marketplace to search. Omit it and you get The default marketplace is searchable by any account, whether you name it or omit it. Naming a DIFFERENT marketplace returns More marketplaces are planned, so read the |
| 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) |
{- "data": [
- {
- "id": "6a024361a30d4d0026d00db2",
- "vin": "string",
- "year": 0,
- "make": "string",
- "model": "string",
- "trim": "string",
- "bodyStyle": "string",
- "mileage": 0,
- "exteriorColor": "string",
- "interiorColor": "string",
- "transmission": "string",
- "driveType": "string",
- "fuel": "string",
- "cylinders": "string",
- "location": "Lehi, UT",
- "marketplaces": [
- "privateauto"
], - "listing": {
- "listingNo": "string",
- "slug": "string",
- "title": "string",
- "price": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
}
], - "_meta": {
- "page": 0,
- "limit": 50,
- "total": 137,
- "hasMore": true
}
}