POST /v1/deals
Create a deal
Create a deal
Creates a deal at stage "lead" with the next number of the tenant. 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 (Idempotent-Replay: true). |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
contactId | string (uuid) | no | |
requestId | string (uuid) | no | |
offerId | string (uuid) | no | |
listingId | string (uuid) | no | |
vehicleId | string (uuid) | no | |
vehicle | object | no | |
vehicle.vin | string | null | no | |
vehicle.make | string | null | no | |
vehicle.model | string | null | no | |
vehicle.trim | string | null | no | |
vehicle.year | integer | null | no | |
vehicle.body | "sedan" | "hatchback" | "wagon" | "suv" | "crossover" | "coupe" | "convertible" | "minivan" | "van" | "pickup" | "truck" | "motorcycle" | "other" | null | no | |
vehicle.fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other" | null | no | |
vehicle.engine | string | null | no | |
vehicle.engineCc | integer | null | no | |
vehicle.powerKw | integer | null | no | |
vehicle.gearbox | "manual" | "automatic" | "cvt" | "robot" | "other" | null | no | |
vehicle.mileageKm | integer | null | no | |
vehicle.color | string | null | no | |
vehicle.source | string | no | |
vehicle.sourceUrl | string | null (uri) | no | |
vehicle.lotId | string | null | no | |
vehicle.titleStatus | "clean" | "salvage" | "rebuilt" | "flood" | "junk" | "parts_only" | "certificate" | "unknown" | null | no | |
type | "full_service" | "auction_only" | "logistics_only" | "resale" | no | |
route | "sea" | "land" | no | |
currency | "UAH" | "USD" | "EUR" | "PLN" | "GEL" | no | |
managerId | string (uuid) | no | |
feeModel | "fixed" | "percent" | no | |
feeValue | number | string | no | |
destinationCountry | string | no | |
destinationCity | string | no | |
note | string | no | |
notifyClient | boolean | no | |
budget | number | string | no | |
requirements | string | no | |
deposit | object | no | |
deposit.amount | number | string | no | |
deposit.dueDate | string (date) | no |
Responses
201
The created deal.
application/json · Schema: DealCreated
| Field | Type | Required | Description |
|---|---|---|---|
deal | object | yes | |
deal.id | string (uuid) | yes | |
deal.number | string | yes | |
deal.status | "lead" | "consult" | "contract_signed" | "deposit_paid" | "searching" | "bid_approved" | "won" | "paid_to_auction" | "pickup_scheduled" | "at_us_warehouse" | "loaded" | "in_transit_sea" | "at_eu_port" | "inland_to_border" | "customs_clearing" | "customs_cleared" | "certification" | "registration" | "ready_for_handover" | "handed_over" | "closed" | "lost" | "cancelled" | "on_hold" | "dispute" | yes | |
deal.pausedFrom | "lead" | "consult" | "contract_signed" | "deposit_paid" | "searching" | "bid_approved" | "won" | "paid_to_auction" | "pickup_scheduled" | "at_us_warehouse" | "loaded" | "in_transit_sea" | "at_eu_port" | "inland_to_border" | "customs_clearing" | "customs_cleared" | "certification" | "registration" | "ready_for_handover" | "handed_over" | "closed" | "lost" | "cancelled" | "on_hold" | "dispute" | null | yes | |
deal.type | "full_service" | "auction_only" | "logistics_only" | "resale" | yes | |
deal.route | "sea" | "land" | yes | |
deal.currency | "UAH" | "USD" | "EUR" | "PLN" | "GEL" | yes | |
deal.contactId | string (uuid) | yes | |
deal.managerId | string | null (uuid) | yes | |
deal.vehicleId | string | null (uuid) | yes | |
deal.destinationCountry | string | null | yes | |
deal.destinationCity | string | null | yes | |
deal.etaDelivery | string | null | yes | ISO 8601 date-time (UTC). |
deal.stageDates | object | yes | stage -> time of entering it. |
deal.trackingToken | string (uuid) | yes | Token of the public tracking page (Track). |
deal.trackingEnabled | boolean | yes | |
deal.lostReason | string | null | yes | |
deal.closedAt | string | null | yes | ISO 8601 date-time (UTC). |
deal.createdAt | string | yes | ISO 8601 date-time (UTC). |
deal.updatedAt | string | yes | ISO 8601 date-time (UTC). |
taskIds | string (uuid)[] | yes |
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
Contact, request, offer or listing not found in this tenant.
application/problem+json · Schema: Problem
409
Conflict: duplicate contact (duplicate_ids), a request with this Idempotency-Key is still being processed, or the stage transition is blocked (missing[]).
application/problem+json · Schema: Problem
422
Well-formed but not acceptable data (unprocessable_input), or Idempotency-Key reused with a different request.
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