POST /v1/extension/lot
Add a lot to Desk: vehicle + offer for a client request
Add a lot to Desk: vehicle + offer for a client request
Creates a vehicle (source "extension"; the same lot is not duplicated) and an offer for the chosen client request. The client-facing snapshot merges lot price, auction fees and the broker fee into one line and never contains the margin. With send=true the offer is sent to the client right away (event request.offer_sent; delivery to Telegram/cabinet is done by the notification worker). Supports Idempotency-Key. Requires scope write:deals.
- Authentication: header
Authorization: Bearer rv_live_...(API keys and scopes) - Required scope:
write:deals
openapi.json).Parameters
| Field | In | Type | Required | Description |
|---|---|---|---|---|
idempotency-key | header | string | no | Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
request_id | string (uuid) | yes | Client request (from GET /v1/extension/requests) the offer is made for. |
lot | object | yes | |
lot.auction | "copart" | "iaai" | yes | |
lot.lot_id | string | yes | |
lot.url | string (uri) | yes | Link to the lot page. |
lot.title | string | yes | |
lot.vin | string | no | |
lot.make | string | no | |
lot.model | string | no | |
lot.year | integer | no | |
lot.fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other" | no | |
lot.engine_cc | integer | no | |
lot.kwh | number | no | |
lot.mileage_km | integer | no | |
lot.damage_primary | string | no | |
lot.damage_secondary | string | no | |
lot.title_status | "clean" | "salvage" | "rebuilt" | "flood" | "junk" | "parts_only" | "certificate" | "unknown" | no | |
lot.yard | string | no | |
lot.us_state | string | no | |
lot.price_usd | number | no | Current bid or buy-now price in USD. |
lot.photos | string (uri)[] | no | |
landed | object | yes | |
landed.currency | string | yes | |
landed.total | number | yes | |
landed.country | "UA" | "PL" | "LT" | "GE" | "DE" | yes | |
landed.confidence | number | no | |
landed.items | object[] | yes | Landed cost lines in currency. The client sees them aggregated: lot, auction fees and the broker fee are merged into one "vehicle and services" line. |
landed.items[].kind | "lot_price" | "auction_fee" | "broker_fee" | "inland_us" | "ocean" | "port" | "inland_eu" | "customs_duty" | "excise" | "vat" | "broker_customs" | "certification" | "pension_fund" | "registration" | "repair" | "detailing" | "insurance" | "our_fee" | "other" | no | |
landed.items[].amount | number | no | |
message | string | no | Text for the client. |
send | boolean | no | true: send the offer to the client right away (Telegram by default). |
channel | "telegram" | "viber" | "email" | "sms" | "webhook" | "in_app" | no |
Responses
201
Created.
application/json · Schema: ExtensionLotResponse
| Field | Type | Required | Description |
|---|---|---|---|
vehicle_id | string (uuid) | yes | |
offer_id | string (uuid) | yes | |
request_id | string (uuid) | yes | |
contact_id | string (uuid) | yes | |
status | "draft" | "sent" | yes | |
price_total | string | null | yes | |
currency | string | null | yes | |
desk_path | string | yes | Path in Desk where the request with the offer is shown. |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Schema: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Schema: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Schema: Problem
404
The request does not exist in this tenant.
application/problem+json · Schema: Problem
409
The offer cannot be created or sent in the current state.
application/problem+json · Schema: Problem
422
Invalid data (e.g. VIN checksum).
application/problem+json · Schema: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Schema: Problem