POST /v1/leads
Register a lead
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.
- Автентифікація: заголовок
Authorization: Bearer rv_live_...(API-ключі та scopes) - Потрібний scope:
write:deals
openapi.json) і подається англійською, як у самому API.Параметри
| Поле | Де | Тип | Обов’язк. | Опис |
|---|---|---|---|---|
idempotency-key | header | string | ні | Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response (Idempotent-Replay: true). |
Тіло запиту
| Поле | Тип | Обов’язк. | Опис |
|---|---|---|---|
form | string | ні | |
fullName | string | null | ні | |
phone | string | null | ні | |
email | string | null | ні | |
telegramId | string | number | null | ні | |
telegramUsername | string | null | ні | |
viberId | string | null | ні | |
locale | "uk" | "pl" | "en" | ні | |
message | string | null | ні | |
utm | object | ні | |
referrer | string | null | ні | |
landingUrl | string | null | ні | |
consentMarketing | boolean | ні | |
ownerUserId | string | null (uuid) | ні | |
request | object | ні | |
request.budgetMin | number | string | null | ні | |
request.budgetMax | number | string | null | ні | |
request.currency | "UAH" | "USD" | "EUR" | "PLN" | "GEL" | ні | |
request.markets | "us" | "eu" | "cn" | "kr" | "ua" | "ge"[] | ні | |
request.make | string | null | ні | |
request.model | string | null | ні | |
request.yearFrom | integer | null | ні | |
request.yearTo | integer | null | ні | |
request.body | "sedan" | "hatchback" | "wagon" | "suv" | "crossover" | "coupe" | "convertible" | "minivan" | "van" | "pickup" | "truck" | "motorcycle" | "other"[] | ні | |
request.fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other"[] | ні | |
request.gearbox | "manual" | "automatic" | "cvt" | "robot" | "other"[] | ні | |
request.mileageMax | integer | null | ні | |
request.mustHave | object | ні | |
request.destinationCountry | string | null | ні | |
request.destinationCity | string | null | ні | |
request.searchQuery | object | ні | |
request.searchQuery.text | string | ні | |
request.searchQuery.make | string | ні | |
request.searchQuery.model | string | ні | |
request.searchQuery.yearFrom | integer | ні | |
request.searchQuery.yearTo | integer | ні | |
request.searchQuery.priceMin | object | ні | |
request.searchQuery.priceMax | object | ні | |
request.searchQuery.mileageMaxKm | number | ні | |
request.searchQuery.fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other"[] | ні | |
request.searchQuery.gearbox | "manual" | "automatic" | "cvt" | "robot" | "other"[] | ні | |
request.searchQuery.body | "sedan" | "hatchback" | "wagon" | "suv" | "crossover" | "coupe" | "convertible" | "minivan" | "van" | "pickup" | "truck" | "motorcycle" | "other"[] | ні | |
request.searchQuery.drive | "fwd" | "rwd" | "awd" | "4wd"[] | ні | |
request.searchQuery.markets | "us" | "eu" | "cn" | "kr" | "ua" | "ge"[] | ні | |
request.searchQuery.countries | string[] | ні | |
request.searchQuery.noAccidents | boolean | ні | |
request.searchQuery.sourceKeys | string[] | ні | |
request.searchQuery.limit | integer | ні | |
request.searchQuery.page | integer | ні | |
request.notes | string | null | ні | |
quiz | object | ні | |
calculator | object | ні | |
listingId | string | null (uuid) | ні | |
externalRef | string | null | ні |
Відповіді
201
The lead was registered.
application/json · Схема: LeadResult
| Поле | Тип | Обов’язк. | Опис |
|---|---|---|---|
contactId | string (uuid) | так | |
isNew | boolean | так | false: an existing contact was found by phone/email/Telegram and updated. |
ownerUserId | string | null (uuid) | так | |
requestId | string | null (uuid) | так | |
taskId | string | null (uuid) | так | |
replay | boolean | так | true: the same externalRef was already processed; nothing changed. |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Схема: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Схема: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Схема: 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 · Схема: Problem
422
Well-formed but not acceptable data (unprocessable_input), or Idempotency-Key reused with a different request.
application/problem+json · Схема: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Схема: Problem