POST /v1/leads

Register a lead

The single entry point for leads: finds an existing contact by phone/email/Telegram (and updates it) or creates one, assigns an owner (round-robin if enabled), creates a search request when search parameters are given and a "contact the lead" task. Supports Idempotency-Key and externalRef. Requires scope write:deals.

Authentication: header Authorization: Bearer rv_live_... (API keys and scopes)
Required scope: write:deals

Descriptions of the operation, parameters and fields come from the OpenAPI specification (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
`form`	`string`	no
`fullName`	`string \| null`	no
`phone`	`string \| null`	no
`email`	`string \| null`	no
`telegramId`	`string \| number \| null`	no
`telegramUsername`	`string \| null`	no
`viberId`	`string \| null`	no
`locale`	`"uk" \| "pl" \| "en"`	no
`message`	`string \| null`	no
`utm`	`object`	no
`referrer`	`string \| null`	no
`landingUrl`	`string \| null`	no
`consentMarketing`	`boolean`	no
`ownerUserId`	`string \| null (uuid)`	no
`request`	`object`	no
`request.budgetMin`	`number \| string \| null`	no
`request.budgetMax`	`number \| string \| null`	no
`request.currency`	`"UAH" \| "USD" \| "EUR" \| "PLN" \| "GEL"`	no
`request.markets`	`"us" \| "eu" \| "cn" \| "kr" \| "ua" \| "ge"[]`	no
`request.make`	`string \| null`	no
`request.model`	`string \| null`	no
`request.yearFrom`	`integer \| null`	no
`request.yearTo`	`integer \| null`	no
`request.body`	`"sedan" \| "hatchback" \| "wagon" \| "suv" \| "crossover" \| "coupe" \| "convertible" \| "minivan" \| "van" \| "pickup" \| "truck" \| "motorcycle" \| "other"[]`	no
`request.fuel`	`"petrol" \| "diesel" \| "hybrid" \| "phev" \| "ev" \| "lpg" \| "cng" \| "hydrogen" \| "other"[]`	no
`request.gearbox`	`"manual" \| "automatic" \| "cvt" \| "robot" \| "other"[]`	no
`request.mileageMax`	`integer \| null`	no
`request.mustHave`	`object`	no
`request.destinationCountry`	`string \| null`	no
`request.destinationCity`	`string \| null`	no
`request.searchQuery`	`object`	no
`request.searchQuery.text`	`string`	no
`request.searchQuery.make`	`string`	no
`request.searchQuery.model`	`string`	no
`request.searchQuery.yearFrom`	`integer`	no
`request.searchQuery.yearTo`	`integer`	no
`request.searchQuery.priceMin`	`object`	no
`request.searchQuery.priceMax`	`object`	no
`request.searchQuery.mileageMaxKm`	`number`	no
`request.searchQuery.fuel`	`"petrol" \| "diesel" \| "hybrid" \| "phev" \| "ev" \| "lpg" \| "cng" \| "hydrogen" \| "other"[]`	no
`request.searchQuery.gearbox`	`"manual" \| "automatic" \| "cvt" \| "robot" \| "other"[]`	no
`request.searchQuery.body`	`"sedan" \| "hatchback" \| "wagon" \| "suv" \| "crossover" \| "coupe" \| "convertible" \| "minivan" \| "van" \| "pickup" \| "truck" \| "motorcycle" \| "other"[]`	no
`request.searchQuery.drive`	`"fwd" \| "rwd" \| "awd" \| "4wd"[]`	no
`request.searchQuery.markets`	`"us" \| "eu" \| "cn" \| "kr" \| "ua" \| "ge"[]`	no
`request.searchQuery.countries`	`string[]`	no
`request.searchQuery.noAccidents`	`boolean`	no
`request.searchQuery.sourceKeys`	`string[]`	no
`request.searchQuery.limit`	`integer`	no
`request.searchQuery.page`	`integer`	no
`request.notes`	`string \| null`	no
`quiz`	`object`	no
`calculator`	`object`	no
`listingId`	`string \| null (uuid)`	no
`externalRef`	`string \| null`	no

Responses

201

The lead was registered.

application/json · Schema: LeadResult

Field	Type	Required	Description
`contactId`	`string (uuid)`	yes
`isNew`	`boolean`	yes	false: an existing contact was found by phone/email/Telegram and updated.
`ownerUserId`	`string \| null (uuid)`	yes
`requestId`	`string \| null (uuid)`	yes
`taskId`	`string \| null (uuid)`	yes
`replay`	`boolean`	yes	true: the same externalRef was already processed; nothing changed.